Лучшие практики разработки REST API: 20 советов

Наверняка вам попадался ужасный API, работая с которым приходилось угадывать, что он ждёт на входе, и что вы получите на выходе. В этой статье мы поговорим о лучших практиках по разработке REST API.

Немного терминов

Дизайн любого API должен следовать правилам Дизайна Ориентированного на Ресурсы. Здесь есть три ключевые идеи:

• Ресурс — это часть данных, например данные о пользователе.
• Коллекция — это группа ресурсов, например список пользователей.
• URL — определяет местонахождение ресурса или коллекции, например /user.

1. Используйте kebab-case для URL

Google рекомендует использовать kebab-case.

Вот пример для списка заказов.

Плохо:

			/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 ресурсов

Вместо этого пользуйтесь HTTP методами для описания операций.

Плохо:

			POST /updateuser/{userId} или GET /getusers
		

Хорошо:

			PUT /user/{userId}
		

6. Пользуйтесь глаголами в URL операций

Например, если вы хотите переслать уведомление пользователю.

Хорошо:

			POST /alerts/245743/resend
		

Помните, что resend не является CRUD операцией. Наоборот, это функция, которая выполняет определённое действие на сервере.

7. Используйте camelCase для JSON свойств

Плохо:

			{
   user_name: "Mohammad Faisal",
   user_id: "1"
}
		

Хорошо:

			{
   userName: "Mohammad Faisal",
   userId: "1"
}
		

8. Состояние

RESTful HTTP сервисы обязаны реализовывать методы /health, /version и /metrics.

Подробнее о разработке RESTful.

/health

Ответ на этот запрос — код статуса «200 OK».

/version

Этот запрос возвращает номер версии.

/metrics

Этот запрос возвращает различные метрики вроде времени ответа.

Также рекомендуется реализовать запросы /debug и /status.

9. Используйте инструменты для разработки REST API

Для этих целей достаточно хороших решений, например API Blueprint и Swagger.

С такими инструментами легко обеспечить пользователей адекватной документацией к вашему REST API.

10. Используйте простой порядковый номер для версий

И всегда указывайте его на самом верхнем уровне.

Хорошо:

			http://api.domain.com/v1/shops/3/products
		

11. Указывайте количество ресурсов в ответе на запрос

Это свойство можно назвать total.

Плохо:

			{
  users: [ 
     ...
  ], offset: 0
}
		

Хорошо:

			{
  users: [ 
     ...
  ] offset: 0,
    total: 34
}
		

12. Используйте параметры limit и offset

Хорошо:

			GET /shops?offset=5&limit=5
		

Потому что на фронтенде часто требуется пагинация.

13. Используйте параметр fields

Количество возвращаемых данных имеет значение. С помощью этого параметра пользователи смогут получать только нужные им поля с данными.

Пример:

Вы получите в ответе только поля name, address и contact.

			GET /shops?fields=id,name,address,contact
		

В некоторых случаях это поможет уменьшить вес ответа.

14. Не передавайте аутентификационные токены в URL

Это очень плохая практика, потому что часто URL логгируются, и токен также сохранится.

Плохо:

			GET /shops/123?token=some_kind_of_authenticaiton_token
		

Хорошо:

Вместо этого пользуйтесь заголовками.

			Authorization: Bearer xxxxxx, Extra yyyyy
		

Помните — время жизни токена нужно ограничивать.

15. Проверяйте Content-Type

Если вы принимаете application/x-www-form-urlencoded, злоумышленник может создать форму и вызвать простой POST запрос.

Вы можете воспользоваться стандартным вариантом — content-type: application/json.

16. Используйте HTTP методы для CRUD операций

В этом и есть их смысл.

GET: получение данных о ресурсах.

POST: создание новых ресурсов и подресурсов.

PUT: обновление существующих ресурсов.

PATCH: обновляет только определённые поля существующих ресурсов.

DELETE: удаляет ресурсы.

17. 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. Используйте PUT на URL ресурса, а не коллекции.
• POST /shops создать новый магазин и вернуть данные о нём. Используйте  POST на URL коллекции.

18. CORS

Используйте заголовки для совместного использования ресурсов (CORS) в тех случаях, когда API доступен публично.

Рассмотрите возможность поддержки разрешенного CORS источника «*» и принудительной авторизации с помощью валидных токенов OAuth.

Избегайте сочетания использования идентификационных данных пользователя и валидации источника.

19. Безопасность

Обязательно используйте HTTPS (TLS-encrypted) для всех конечных точек, ресурсов и сервисов.

Также сделайте обязательным HTTPS для всех коллбеков URL, конечных точек пуш-уведомлений и вебхуков.

20. Ошибки

Ошибки сервисов возникают, когда клиент делает некорректный запрос или передаёт неверные данные сервису, и сервис отклоняет запрос.

Например неправильные аутентификационные данные, параметры, id версий и тд.

• Возвращайте ошибку 4xx, когда отклоняете запрос из-за одной или более ошибок сервисов.
• Обеспечьте обработку всех атрибутов и возврат всех ошибок в одном ответе сервера.

Золотые правила

Эти правила помогут вам принимать верные решения во время разработки REST API:

• Не используйте излишнюю вложенность.
• Простое лучше сложного.
• Строки лучше чем числа.
• Единообразность лучше кастомизации.