Проектирование API

Любой API следует так называемому ресурсно-ориентированному дизайну и состоит из трех ключевых концепций

  • ресурс: часть данных, например, User;
  • коллекция: группа ресурсов, например, List of users;
  • URL: местоположение ресурса или коллекции, например, /user.

1. Kebab-case для URL-адресов

Если вы хотите получить список заказов.

Плохо:

/systemOrders или /system_orders

Хорошо:

/system-orders

2. CamelCase для параметров

Применяйте, если хотите получить товары из определенного магазина.

Плохо:

/system-orders/{order_id} или /system-orders/{OrderId}

Хорошо:

/system-orders/{orderId}

3. Множественное число, указывающее на коллекцию

Если необходимо получить всех пользователей системы.

Плохо:

GET /user или GET /User

Хорошо:

GET /users

4. URL начинается с коллекции и заканчивается идентификатором

Если хотите сохранить концепцию единой и последовательной.

Плохо:

GET /shops/:shopId/category/:categoryId/price

Это плохо, потому что здесь описано свойство, а не ресурс.

Хорошо:

GET /shops/:shopId/ или GET /category/:categoryId

5. Не используйте глаголы в URL ресурса

Не используйте глаголы в URL для выражения действий. Вместо этого примените описанные ниже методы.

Плохо:

POST /updateuser/{userId} или GET /getusers

Хорошо:

PUT /user/{userId}

6. Используйте глаголы в URL для Non-Resource

У вас есть код, не возвращающий ничего кроме операции. В этом случае можно использовать глаголы. Например, для повторной отправки предупреждения пользователю.

Хорошо:

POST /alerts/245743/resend

7. Используйте camelCase для свойства JSON

Если у вас есть тело запроса или ответ в JSON, имена свойств должны быть в camelCase.

Плохо:

{
user_name: «Programmer's library»
user_id: «1»
}

Хорошо:

{
userName: «Programmer's library»
userId: «1»
}

8. Мониторинг

Службы HTTP RESTful должны реализовывать конечные точки API /health, /version и /metrics, предоставляющие следующую информацию:

/health – отвечает на запросы с кодом состояния 200 OK;
/version – отвечает на запрос номером версии;
/metrics – эта конечная точка будет предоставлять различные показатели, например, среднее время отклика.
Настоятельно рекомендуем использовать конечные точки /debug и /status.

9. Не используйте table_name для имени ресурса

Не используйте имя таблицы в качестве имени ресурса. В долгосрочной перспективе такая лень может привести к проблемам.

Плохо:

product_order

Хорошо:

product-orders

10. Применяйте инструменты проектирования

Существует много хороших инструментов проектирования API:

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

11. Используйте порядковый номер в качестве версии

Всегда указывайте номер версии для API. Номер версии должен быть v1, v2 и т. д.

Хорошо:

http://api.domain.com/v1/shops/3/products

Если API используется внешними сущностями, изменение конечной точки может нарушить их функциональность, поэтому использование версий обязательно.

12. Выводите в ответе общее количество ресурсов

Если API возвращает список объектов, всегда включайте общее количество ресурсов в ответ.

Плохо:

{
пользователи: [ ... ]
}

Хорошо:

{
пользователи: [ ... ],
всего: 34
}

13. Принимайте параметры ограничения и смещения

Всегда принимайте параметры ограничения и смещения в операциях GET.

Хорошо:

GET /shops?offset=5&limit=5

Это необходимо для пагинации на фронтенде.

14. Получаем поля параметров запроса

Следует учитывать объем возвращаемых данных. Добавьте параметр fields, чтобы предоставить только необходимые поля из вашего API.

Пример:

Вернуть только название, адрес и контакты магазинов.

GET /shops?fields=id,name,address,contact

В некоторых случаях это поможет уменьшить размер ответа.

15. Не передавайте в URL токены аутентификации

Это очень плохая практика, потому что URL часто регистрируются и, следовательно, маркер аутентификации также будет регистрироваться без необходимости.

Плохо:

GET /shops/123?token=some_kind_of_authenticaiton_token

Хорошо:

Вместо этого передайте их в заголовке:

Authorization: Bearer xxxxxx, Extra yyyyy

16. Проверка Content-Type

Сервер не должен принимать content-type. Например, если вы принимаете application/x-www-form-urlencoded, злоумышленник может создать форму и запустить простой запрос POST.

Всегда валидируйте тип контента, а если хотите использовать content-type по умолчанию, используйте application/json.

17. Использование методов HTTP для функций CRUD

Следующие методы служат для описания CRUD-функций:

  • GET: получение представления ресурса.
  • POST: создание новых ресурсов и подресурсов.
  • PUT: обновление существующих ресурсов.
  • PATCH: обновление существующих ресурсов, но только тех полей, которые были описаны (остальные остаются без изменений).
  • DELETE: удаление существующих ресурсов.

18. Применение отношений в URL для вложенных ресурсов

Вот некоторые практические примеры:

  • GET /shops/2/products: получить список всех продуктов из магазина 2.
  • GET /shops/2/products/31: получить подробную информацию о продукте 31, из магазина 2.
  • DELETE /shops/2/products/31: удалить продукт 31 из магазина 2.
  • PUT /shops/2/products/31: обновить информацию о продукте 31 (использовать только URL ресурса, а не коллекцию).
  • POST /shops: создать новый магазин и вернуть сведения о нем.

19. CORS

Поддерживайте заголовки CORS (Cross-Origin Resource Sharing) для всех общедоступных API. Рассмотрите возможность поддержки разрешенного CORS-источника « * » и принудительной авторизации с помощью OAuth-токенов. Избегайте объединения учетных данных пользователя с валидацией происхождения.

20. Безопасность

Применяйте протокол HTTPS (зашифрованный TLS) ко всем конечным точкам, ресурсам и службам. HTTPS должен быть у всех колбеков, эндпоинтов, push-уведомлений и веб-хуков.

21. Ошибки

Ошибки возникают, когда клиент делает неправильный запрос к службе или передает службе неправильные данные, а та отклоняет запрос. Популярные проблемы: неверные учетные данные, неправильные параметры, неизвестные идентификаторы версий и т. д. При отклонении запроса клиента по причине ошибок службы возвращают коды HTTP – 4xx.