21 лучший метод выведет ваши навыки проектирования API на новый уровень

Чтобы не разочаровываться в ужасном API и не играть в угадайку на каждом шагу, стоит использовать лучшие известные практики. Сайт proglib.io опубликовал сокращенный перевод статьи «22 Best Practices to Take Your API Design Skills to the Next Level». Представляем этот обзор вашему вниманию.

Photo by Andrea Piacquadio from Pexels

Немного терминологии

Любой 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/:categoryI

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 Blueprint
  • Swagger

Наличие хорошей и подробной документации обеспечивает отличный клиентский опыт для пользователей 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.

Заключение

Вот и все – поздравляем, если вы зашли так далеко! Надеемся, вы кое-чему научились и будете применять рекомендации статьи в своих проектах. Удачи!

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Прокрутить вверх