Знакомство с REST API: пошаговый план проектирования. Часть 2.

Итак, эта часть для тех, кто уже познакомился с основами REST и готов начинать проектировать собственное API. Здесь мы рассмотрим полный цикл резработки RESTful API.

1. Определение требований.

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

   • выбор ЯП (языка программирования)
   • БД (базы данных)
   • целесообразность подключения и выбор фреймворка (Laravel, Symfony)
2. Определение ресурсов.

   Ресурс в REST API - это объект или данные, с которыми работает API. Это может быть пользователи (users), заказы (orders), товары (products), статьи (articles) или любой другой элемент, который можно запрашивать, создавать, обновлять или удалять. Каждый ресурс имеет свой уникальный URL, и взаимодействие с ним происходит с помощью стандартных методов HTTP.

3. Определение структуры URL (эндпроинтов) и выделение HTTP методов.

   Для выполнения операций над ресурсами, мы должны использовать основные HTTP методы:

   • GET - получение ресурса
   • POST - создание нового ресурса (новая запись в БД, например заявка с сайта)
   • PUT/PATCH - обновление ресурса

     PUT - предполагает полное обновление ресурса (передаются все поля, даже те, где значения не изменились, в противном случае данные в таких полях в БД сбросятся до данных по-умолчанию). Проще реализуются. Лучше кешируется.

     PATCH используется для частичного обновления. Он обновляет только те поля, которые указаны в запросе, а остальные не изменяет. Сложнее реализовать, нужно писать дополнительную логику. Труднее кешируется, также требует определённых настроек.

   • DELETE - удаление данных

   Каждый эндпоинт (конкретный URL-адрес в API) должен соответствовать определённому методу, это делает API более интуитивно понятным и предсказуемым для других разработчиков. Например:

   GET /products — список товаров
   POST /products — добавление нового товара
   GET /products/{product_id} — информация о конкретном товаре

   Плохими практиками использования HTTP методов при проектировании REST API будет:

   • Отправка всех запросов к API только через один метод GET или только через POST.
   • Передача данных JSON в body через GET.
     Многие сетевые фильтры, браузеры просто теряют Body где-то по пути. Имейте это ввиду и используйте только
     Query параметры. Также браузеры имеют ограничения по длине URL: не рекомендуется использовать URL длиной более 2048 символов.
   • Не передаём параметры через заголовки запроса. Делаем это либо через Query-параметры в GET или через JSON в body метода POST/PUT.

   Верные практики проектирования эндпроинтов в REST API:

   Удачные	Неудачные
   GET /api/v1/products/123 • используется верный метод для получения информации • есть версионирование Лучше заранее предусмотреть версионирование, чтобы в будущем можно было обновлять API без нарушения совместимости • наименование ресурса всегда во множественном числе	POST /api/product/123
   GET /users/123 POST /users DELETE /users/123 • эндроинты не засорены глаголами • используется верное применение методов Глаголы в URL не только избыточны, но и сбивают с толку, так как нарушают REST-принципы.	GET /getUser/123 POST /createUser DELETE /deleteUser/123
   PUT /users/123/status Body: { "status": "active" } • эндпроинт не указывает на действие в URL (передача действий в URL противоречит принципам REST) • верное использование метода для обновления ресурса • данные передаются в body через JSON	POST /users/123/activate POST /users/123/deactivate
   POST /users DELETE /users/123 • верное использование методов • действия не передаются через query-параметры и эндпоинт соответствует принципам REST	GET /users?action=create GET /users?action=delete&id=123
   GET /products/123/reviews/456?shop_id=10&department_id=5 • нет большой вложенности, легко читаем • отражает оптимальную структуру данных	GET /shops/10/departments/5/products/123/reviews/456
   GET /products/123 • айди указан как как часть path parameters - правильная идентификация ресурса в REST-принципы	GET /products?id=123

4. Определение формата ответа. Обычно это JSON. В редких случаях XML.
5. Определение кода статусов и обработки ошибок.

   Используем правильные коды статусов HTTP:

   • 200 OK — успешный запрос,
   • 201 Created — ресурс успешно создан,
   • 400 Bad Request — ошибка в запросе,
   • 404 Not Found — ресурс не найден,
   • 500 Internal Server Error — ошибка на сервере.

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

6. Реализация и тестирование.

   На этапе разработки создайте первую версию API и протестируйте её. Это можно сделать с помощью инструментов вроде Postman или автоматизированных тестов, проверяя правильность работы методов и соответствие требованиям.

7. Документирование.

   Наконец, создайте документацию, чтобы сделать API понятным для разработчиков. Инструменты вроде Swagger или Blueprint помогут описать каждый эндпоинт, параметры и возможные ответы.

В заключении подытожим: хорошо спроектированный REST API должен быть простым, логичным и предсказуемым, с чётким разделением обязанностей между URL и HTTP-методами. Так что придерживайтесь принципов, не лепите отсебятины и будет вам счастье в разработке!