Любой API следует так называемому ресурсно-ориентированному дизайну и состоит из трех ключевых концепций.
- ресурс: часть данных, например, User;
- коллекция: группа ресурсов, например, List of users;
- URL: местоположение ресурса или коллекции, например, /user.
1. Kebab-case для URL-адресов
Если вы хотите получить список заказов.
Плохо :
Хорошо :
2. CamelCase для параметров
Применяйте, если хотите получить товары из определенного магазина.
3. Множественное число, указывающее на коллекцию
Если необходимо получить всех пользователей системы.
4. URL начинается с коллекции и заканчивается идентификатором
Если хотите сохранить концепцию единой и последовательной.
Плохо :
Это плохо, потому что здесь описано свойство, а не ресурс.
5. Не используйте глаголы в URL ресурса
Не используйте глаголы в URL для выражения действий. Вместо этого примените описанные ниже методы.
Плохо :
6. Используйте глаголы в URL для Non-Resource
У вас есть код, не возвращающий ничего кроме операции. В этом случае можно использовать глаголы. Например, для повторной отправки предупреждения пользователю.
7. Используйте camelCase для свойства JSON
Если у вас есть тело запроса или ответ в JSON, имена свойств должны быть в camelCase.
Плохо :
Хорошо :
8. Мониторинг
Службы HTTP RESTful должны реализовывать конечные точки API /health, /version и /metrics, предоставляющие следующую информацию:
- /health – отвечает на запросы с кодом состояния 200 OK;
- /version – отвечает на запрос номером версии;
- /metrics – эта конечная точка будет предоставлять различные показатели, например, среднее время отклика.
Настоятельно рекомендуем использовать конечные точки /debug и /status.
9. Не используйте table_name для имени ресурса
Не используйте имя таблицы в качестве имени ресурса. В долгосрочной перспективе такая лень может привести к проблемам.
10. Применяйте инструменты проектирования
Существует много хороших инструментов проектир ования API:
- API Blueprint
- Swagger
Наличие хорошей и подробной документации обеспечивает отличный клиентский опыт для пользователей API.
11. Используйте порядковый номер в качестве версии
Всегда указывайте номер версии для API. Номер версии должен быть v1, v2 и т. д.
Если API используется внешними сущностями, изменение конечной точки может нарушить их функциональность, поэтому использование версий обязательно.
12. Выводите в ответе общее количество ресурсов
Если API возвращает список объектов, всегда включайте общее количество ресурсов в ответ.
13. Принимайте параметры ограничения и смещения
Всегда принимайте параметры ограничения и смещения в операциях GET.
Это необходимо для пагинации на фронтенде.
14. Получаем поля параметров запроса
Следует учитывать объем возвращаемых данных. Добавьте параметр fields, чтобы предоставить только необходимые поля из вашего API.
Вернуть только название, адрес и контакты магазинов.
В некоторых случаях это поможет уменьшить размер ответа.
15. Не передавайте в URL токены аутентификации
Это очень плохая практика, потому что URL часто регистрируются и, следовательно, маркер аутентификации также будет регистрироваться без необходимости.
Плохо :
Вместо этого передайте их в заголовке:
Кроме того, токены авторизации должны быть недолговечными.
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. Ошибки
Ошибки возникают, когда клиент делает неправильный запрос к службе или передает службе неправильные данные, а та отклоняет запрос. Популярные проблемы: неверные учетные данные, неправильные параметры, неизвестные идентификаторы версий и т. д.
Заключение
Вот и все – поздравляем, если вы зашли так далеко! Надеемся, вы кое-чему научились и будете применять рекомендации статьи в своих проектах. Удачи!