При проектировании 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.