Перевод публикуется с сокращениями, автор оригинальной статьи 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. Ошибки
Ошибки возникают, когда клиент делает неправильный запрос к службе или передает службе неправильные данные, а та отклоняет запрос. Популярные проблемы: неверные учетные данные, неправильные параметры, неизвестные идентификаторы версий и т. д.
Заключение
Вот и все – поздравляем, если вы зашли так далеко! Надеемся, вы кое-чему научились и будете применять рекомендации статьи в своих проектах. Удачи!
Дополнительные материалы:
Комментарии