Руководство по именованию ресурсов RESTful API (именование URI)

При проектировании API очень важно иметь соглашение об именовании ресурсов API, которое соблюдается последовательно. В сочетании с правильным использованием HTTP-глаголов это помогает стандартизировать доступ к API и снизить потенциальные проблемы безопасности. Вот краткое руководство по именованию ресурсов и конечных точек REST API, которое поможет вам разработать интуитивно понятные, простые в использовании API, которые заставят разработчиков фронтенда влюбиться в вас 😉.

URI как ресурсы (существительные)

Одна из самых распространенных ошибок, которую допускают разработчики API, включая меня, это неправильное использование существительных и глаголов в REST URI. Вот краткая заметка, которая поможет вам понять именование REST URI:

REST API используются для получения и манипулирования ресурсами (существительные), а не действиями (глаголы). Поэтому REST URI не должны указывать на какие-либо действия или функции CRUD (Create, Read, Update, Delete).

Примеры:

// Get all user resources
GET "https://example.com/api/v1/users" // Correct
GET "https://example.com/api/v1/listUsers" // Wrong

// Update a single photo resource
PUT "https://example.com/api/v1/photos/{id}" // Correct
PUT "https://example.com/api/v1/updatePhoto/{id}" // Wrong
Войти в полноэкранный режим Выход из полноэкранного режима

Множественные ресурсы

Если у вас нет единственного или функционального ресурса, вы должны использовать множественное число для всех имен ресурсов.

Примеры

"/users/{id}"
"/schema" // Singleton resource
"/auth/login" // Function resource
Войти в полноэкранный режим Выйти из полноэкранного режима

Иерархия ресурсов

Ресурс может иметь подколлекции ресурсов. Обычно иерархия между отдельными ресурсами и коллекциями отображается с помощью косой черты Forward.

Пример:
Получить все ресурсы заказов, которые относятся к одному ресурсу клиента.

GET "/customers/123/orders"
Вход в полноэкранный режим Выход из полноэкранного режима

Буквы и тире

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

Пример

"/users/123/pending-orders" // Correct
"/users/123/pendingOrders" // Wrong
"/users/123/pending_orders" // Wrong
Войти в полноэкранный режим Выход из полноэкранного режима

Дополнительные советы

  • Не сокращать. /users/{id}/phone-number вместо /users/{id}/tel-no.
  • Отсутствует передняя косая черта. /users/{id}/pending-orders вместо /users/{id}/pending-orders/
  • Последовательность — это ключ
  • Используйте параметры запроса для фильтрации, сортировки или ограничения коллекции URI. /users?country=ZM&sort=createdAt&limit=100

Пожалуйста, комментируйте, чтобы поделиться другими лучшими практиками, когда речь идет о RESTFul API.

Оцените статью
devanswers.ru
Добавить комментарий