Проектирование RESTful API - лучшие практики

1659952857776.png

В этой статье мы рассмотрим лучшие практики проектирования restful api. Она была подготовлена в предположении, что у вас есть знания по этой теме. Я постарался объяснить тему, не вдаваясь в излишние подробности.

Не существует единственно верного способа проектирования API. Мы должны думать об API как об интерфейсе. Поэтому, когда разработчик взаимодействует с API, он должен быть простым для понимания и легким в использовании. Опыт разработчиков - лучшая метрика в этом отношении.

API endpoint​

Давайте напишем несколько API для Garage, который имеет несколько Car, чтобы понять больше.

  • URL должен содержать только ресурсы (nouns (существительные)), а не действия или глаголы.
  • Именно здесь играют роль методы HTTP (GET, POST, DELETE, PUT), также называемые глаголами.
    В конечной точке API ресурс всегда должен быть во множественном числе, и если мы хотим получить доступ к одному экземпляру ресурса, мы всегда должны передавать его id в URL.
1659953100985.png
Другими вариантами использования могут быть случаи, когда ресурс имеет под собой ресурсы, например, "Garage fo a Car", тогда несколько примеров конечных точек API могут быть следующими:

  • PUT / garages/3 должен обновить гараж 3
  • GET /garages/3/cars должен получить список всех автомобилей из гаража 3
  • GET /garages/3/cars/45 должен получить информацию об автомобиле 45, который принадлежит гаражу 3
  • DELETE /garages/3/cars/45 должен удалить автомобиль 45, принадлежащий гаражу 3
  • POST /garages должен создать новый гараж и вернуть данные о созданном гараже
Заключение: Пути должны содержать форму множественного числа ресурсов, а метод HTTP должен определять вид действия, которое должно быть выполнено над ресурсом.

1659953325480.png

HTTP методы​

В HTTP определены наборы методов, которые указывают на тип действия, выполняемого над ресурсами.
  1. Метод GET запрашивает данные из ресурса и не должен вызывать никаких побочных эффектов.
  2. Метод POST запрашивает сервер для создания ресурса в базе данных, в основном при отправке веб-формы.
  3. Метод PUT запрашивает сервер для обновления (update) ресурса или создания (create)ресурса, если он не существует.
  4. Метод DELETE запрашивает, чтобы ресурс или его экземпляр был удален (remove) из базы данных.

Коды состояния ответа HTTP​

Когда вы обращаетесь к API, сервер отправляет обратно HTTP-код, сигнализирующий о статусе вашего запроса.

Важные коды состояния:

200s Успешные ответы
Например: 200 Ok Стандартный ответ HTTP, представляющий успех для GET, PUT или POST.

300s Перенаправления
Например: 304 Not Modified указывает на то, что ответ уже находится в кэше клиента. Поэтому нет необходимости передавать те же данные повторно.

400s Ошибки клиента
Например: 400 Bad Request означает, что запрос клиента не был обработан, так как сервер не смог понять, о чем просит клиент.

500s Ошибки сервера
Например: 500 Internal Server Error указывает на то, что запрос действителен, но сервер полностью запутался, и серверу предлагается обслужить какое-то неожиданное условие.

Поиск, сортировка, фильтрация и пагинация​


1659954701264.png
Поиск, сортировка, фильтрация и пагинация - это все действия, которые могут быть выполнены над коллекцией API. Это позволяет получать, сортировать и упорядочивать только необходимые данные на страницах, чтобы не перегружать сервер запросами.

Сортировка:

Позволяет сортировать по возрастанию и убыванию по полям.

Код:
GET vehicle-damage-inquiry?sort=id,desc

Фильтрация:

Для фильтрации набора данных мы можем передавать различные параметры через параметры запроса.

Код:
GET vehicle-damage-inquiry?userId={{}}&chassisOrPlate={{}}

Пагинация:

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

Код:
GET vehicle-damage-inquiry?userId={{}}&chassisOrPlate={{}}&page= {{}}&size={{}}

Версионирование​

Используется при разработке API для информирования клиентов, чтобы не ломать существующие продукты или услуги и заставить клиентов использовать новейшую версию.

Код:
GET http://api.carservice.com/v1/brand-new-car/cid

Мы используем url для версий API, начинающийся с буквы "v", если вы вносите изменения, которые несовместимы со старой версией, вам следует увеличить число рядом с "v", например, v2 или v1.x.x.

Код:
GET http://api.carservice.com/v1.1.2/brand-new-car/cid

Документация​

Когда вы создаете API, вам необходимо помочь клиентам научиться и понять, как правильно его использовать. Лучший способ сделать это - предоставить хорошую документацию по API.

Одним из наиболее распространенных инструментов, которые вы можете использовать для документации API, является Swagger.

Заключение

Разрабатывая API, я постарался поделиться с вами самой необходимой информацией. Некоторые материалы в моей статье основаны на моем собственном опыте, некоторые взяты из других источников.​

Ссылки

 
Верх