Евгений Левада 29 апреля 2021

🕸 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.

Всегда валидируйте тип контента, а если хотите использовать 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.

Заключение

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

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

Источники

МЕРОПРИЯТИЯ

Комментарии

ВАКАНСИИ

Добавить вакансию

ЛУЧШИЕ СТАТЬИ ПО ТЕМЕ