Чтобы не разочаровываться в ужасном API и не играть в угадайку на каждом шагу, стоит использовать лучшие известные практики. Сайт proglib.io опубликовал сокращенный перевод статьи «22 Best Practices to Take Your API Design Skills to the Next Level». Представляем этот обзор вашему вниманию.
Немного терминологии
Любой 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
Наличие хорошей и подробной документации обеспечивает отличный клиентский опыт для пользователей 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.
Заключение
Вот и все – поздравляем, если вы зашли так далеко! Надеемся, вы кое-чему научились и будете применять рекомендации статьи в своих проектах. Удачи!
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
