В этой статье мы рассмотрим лучшие практики проектирования restful api. Она была подготовлена в предположении, что у вас есть знания по этой теме. Я постарался объяснить тему, не вдаваясь в излишние подробности.
Не существует единственно верного способа проектирования API. Мы должны думать об API как об интерфейсе. Поэтому, когда разработчик взаимодействует с API, он должен быть простым для понимания и легким в использовании. Опыт разработчиков - лучшая метрика в этом отношении.
API endpoint
Давайте напишем несколько API для Garage, который имеет несколько Car, чтобы понять больше.- URL должен содержать только ресурсы (nouns (существительные)), а не действия или глаголы.
- Именно здесь играют роль методы HTTP (GET, POST, DELETE, PUT), также называемые глаголами.
В конечной точке API ресурс всегда должен быть во множественном числе, и если мы хотим получить доступ к одному экземпляру ресурса, мы всегда должны передавать его id в URL.
- 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 методы
В HTTP определены наборы методов, которые указывают на тип действия, выполняемого над ресурсами.- Метод GET запрашивает данные из ресурса и не должен вызывать никаких побочных эффектов.
- Метод POST запрашивает сервер для создания ресурса в базе данных, в основном при отправке веб-формы.
- Метод PUT запрашивает сервер для обновления (update) ресурса или создания (create)ресурса, если он не существует.
- Метод 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 указывает на то, что запрос действителен, но сервер полностью запутался, и серверу предлагается обслужить какое-то неожиданное условие.
Поиск, сортировка, фильтрация и пагинация
Сортировка:
Позволяет сортировать по возрастанию и убыванию по полям.
Код:
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, я постарался поделиться с вами самой необходимой информацией. Некоторые материалы в моей статье основаны на моем собственном опыте, некоторые взяты из других источников.
Ссылки
Postman
www.postman.com
Postman
www.postman.com
W3Schools Free Online Web Tutorials
W3Schools offers free online tutorials, references and exercises in all the major languages of the web. Covering popular subjects like HTML, CSS, JavaScript, Python, SQL, Java, and many, many more.