Интро

Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.

В тексте попадаются комментарии переводчика, они выделены курсивом.

Собираем API-интерфейсы, которые понравятся другим разработчикам

Понятные URL для вызовов API

Первый принцип хорошего REST-дизайна — делать вещи понятно и просто. Начинать стоит с основных URL адресов для ваших вызовов API.

Ваши адреса вызовов должны быть понятными даже без документации. Для этого возьмите себе за правило описывать любую сущность с помощью коротких и ясных базовых URL адресов, содержащих максимум 2 параметра. Вот отличный пример:

/dogs для работы со списком собак
/dogs/12345 для работы с отдельной собакой

Часть 1: Введение.
Часть 2: Многопоточность
Часть 3: Рендеринг (Прим. пер. — в процессе перевода)
Часть 4: Doom classic — интеграция (Прим. пер. — в процессе перевода)

26 ноября 2012 ID Software выпустила исходный код Doom 3 BFG edition (всего через месяц после появления игры на прилавках магазинов). Движок idTech4, которому уже почти 10 лет, был обновлен решениями, используемыми в idTech 5 (Rage — первая игра на этом движке), и с его исходным кодом ознакомиться было очень интересно.

Я бы назвал движок «idTech4 улучшенный», т.к. по сути это idTech4, но с использованием элементов idTech5:

• Систему управления потоками (Threading system)
• Звуковую систему (Sound system)
• Систему управления ресурсами (Resources system)

Часть 1: Введение
Часть 2: Многопоточность
Часть 3: Рендеринг (Прим. пер. — в процессе перевода)
Часть 4: Doom classic — интеграция (Прим. пер. — в процессе перевода)

Движок для Doom III был написан в период с 2000 по 2004 год, в то время, когда большинство ПК были однопроцессорными. Хотя архитектура движка idTech4 разрабатывалась с учетом поддержки SMP, это закончилось тем, что поддержка многопоточности делалась в последнюю минуту (см. интревью с Джоном Кармаком).

Архитектура USB содержит несколько уровней. На самом низком уровне специально обученное железо, называемое хост-контроллером (host controller), общается с USB-устройством специальными сигналами. Сигналы кодируют биты, биты складываются в пакеты, пакеты образуют транзакции, транзакции составляют передачи (transfers).

Я рассказываю о программной поддержке USB, поэтому уровни ниже передач почти неинтересны: за них отвечает хост-контроллер. Зато важно, какой интерфейс представляет хост-контроллер софту. Сейчас распространены три интерфейса, и постепенно распространяется четвёртый:

Аббр.	Название интерфейса	Версия	Код поддержки контроллера в KolibriOS
UHCI	Universal Host Controller Interface	USB 1.1	kernel/trunk/bus/usb/uhci.inc
OHCI	Open Host Controller Interface	USB 1.1	kernel/trunk/bus/usb/ohci.inc
EHCI	Enhanced Host Controller Interface	USB 2.0	kernel/trunk/bus/usb/ehci.inc
XHCI	eXtensible Host Controller Interface (новый)	USB 3.0	В KolibriOS ещё не поддерживается

На этом же уровне взаимодействия с контроллерами находятся файлы kernel/trunk/bus/usb/hccommon.inc, где реализованы некоторые функции, общие для всех контроллеров, и kernel/trunk/bus/usb/init.inc, который запускает всю подсистему. Впрочем, не торопитесь пока лезть в код — во-первых, я ещё не рассказала про то, чего же ожидают от него более высокие уровни, а во-вторых, после демонстрации общей схемы я вернусь к отдельным компонентам с подробностями.