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

Лучшие практики разработки 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:

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

Хинт для программистов: если зарегистрируетесь на соревнования Huawei Cup, то бесплатно получите доступ к онлайн-школе для участников. Можно прокачаться по разным навыкам и выиграть призы в самом соревновании.

Перейти к регистрации

Источник 22 Best Practices to Take Your API Design Skills to the Next Level