Создании API не похоже на разработку типичного веб-приложения. В API нет пользовательского интерфейса, но есть интерфейс для взаимодействия программ. Часто из-за этого создание API занимает гораздо больше времени, чем планируется в начале. Хочу поделиться соображениями, которые позволяют тратить меньше времени на разработку API.

Используйте HTTP

В качестве базового протокола для API удобно использовать HTTP по ряду причин:

• в большинстве языков программирования есть библиотеки для работы с HTTP, что сокращает время разработки клиента и сервера;
• HTTP – текстовый протокол, это упрощает его отладку;
• при использовании HTTP будет минимум проблем с прокси-серверами;
• при необходимости HTTP можно расширять.

Используйте REST

Архитектура REST делает API простым для изучения и разработки. Неочевидный её плюс – упрощение процедуры инвалидации кэша.

Используйте JSON

Хороший формат вывода данных в API уменьшает время разработки не только сервера, но и клиентских приложений. Я рекомендую использовать JSON: он занимает мало места, является текстовым (я значит прост в отладке), и для него можно написать клиент прямо в JavaScript-консоли браузера.

Предусмотрите механизм версионирования

С изменениями в API есть одна проблема – их нельзя делать без риска поломать клиенты, которые используют это API. Если ваши клиенты – мобильные приложения, то часть из них обязательно не будет обновляться.

Чтобы изменения не поломали обратную совместимость, можно выпустить новую версию API. Версионирование API на HTTP можно делать с помощью с помощью URL http://example.com/api/v1/friends.json, или заголовка, в котором клиент указывает нужную версию API.

Самое главное: предусмотрите версионность вашего API заранее. Это не усложнит разработку, зато значительно сэкономит время при запуске новых версий API.

Документируйте API

Несмотря на то, что API используют программы, проектируют их использование люди. Даже если ваше API не будет опубликовано, напишите документацию к нему.

Простого описания в гугл-документе может быть достаточно. Для каждого запроса укажите: назначение, способ вызова, пример ответа и список возвращаемых ошибок. Хорошая документация к API описывает его возможности, даёт примеры запросов для «быстрого старта», и описывает общие процедуры – паджинацию, авторизацию, формат вывода данных.

Смотрите также

• гем Grape
• Разработка web API
• Swagger

---

comments powered by Disqus

---