Правила наименования являются ключевыми для создания понятного и согласованного API. Они помогают разработчикам легко ориентироваться в структуре API и взаимодействовать с ним. Вот некоторые рекомендации по наименованию для REST API:
1. Используйте множественное число для коллекций
- Названия ресурсов должны быть во множественном числе, например:
/users (для коллекции пользователей)/products (для коллекции продуктов)
2. Избегайте глаголов в URL
- URL должен описывать ресурсы, а не действия. Например:
- Правильно:
/users (получить список пользователей)
- Неправильно:
/getUsers
3. Используйте императивный стиль
- Если вам нужно создать действие, используйте существительные:
- Вместо
/createUser используйте /users с методом POST.
4. Читаемость
- Для улучшения читаемости используйте дефисы или подчеркивания:
- Лучше:
/user-roles или /user_roles
5. Структура ресурсов
- Для обеспечения логичности и иерархии используйте вложенные ресурсы:
/users/{userId}/orders (заказы конкретного пользователя)
6. Использование подчеркиваний и дефисов
- Обычно предпочтение отдается дефисам, поскольку они более читаемы в URL:
- Правильно:
/user-groups
- Неправильно:
/user_groups
7. Версионирование
- Если планируется обновление API, используйте версионирование в URL:
8. Стандартные параметры запроса
- При наименовании параметров придерживайтесь логики:
- Например, используйте
sort, filter, page, limit для параметров пагинации и сортировки.
9. Используйте согласованные форматы данных
- Для параметров и тела запроса используйте постоянные форматы (например, CamelCase или snake_case) во всем API.
Примеры правильного наименования
-
Запрос на получение всех пользователей:
- URL:
/v1/users
- Метод: GET
-
Запрос на создание нового продукта:
- URL:
/v1/products
- Метод: POST
-
Запрос на получение конкретного заказа пользователя:
- URL:
/v1/users/{userId}/orders/{orderId}
- Метод: GET
Почитать
Следование этим правилам поможет сделать ваш API более понятным и удобным для разработчиков.
