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

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

Перевод публикуется с сокращениями, автор оригинальной статьи Mohammad Faisal.

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

Любой 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 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.

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.

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

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

21. Ошибки

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

Заключение

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

Дополнительные материалы:

• Как превратить базу данных в RESTful API
• VK API на Python: часть 1, выгружаем все фото из альбома
  
• Приручи бессерверность: 7 шагов создания бессерверного API
  
• Python и API: превосходное комбо для автоматизации работы с публичными данными
  
• Хватит использовать REST для API!
  

Источники

• https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9