Share This
Связаться со мной
Крути в низ
Categories
//21 лучший метод выведет ваши навыки проектирования API на новый уровень

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

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

21 luchshij metod vyvedet vashi navyki proektirovanija api na novyj uroven 8523e45 - 21 лучший метод выведет ваши навыки проектирования 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/: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

21 luchshij metod vyvedet vashi navyki proektirovanija api na novyj uroven 73ac6a0 - 21 лучший метод выведет ваши навыки проектирования 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.

Заключение

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

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

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

  • 3 views
  • 0 Comment

Leave a Reply

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

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.

Связаться со мной
Close