Структура постановки задачи на REST API метод

для Backend-разработчика

17 января 2024

Автор: Екатерина Ананьева

REST API

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

Введение

Вариант структуры постановки задачи на REST API метод на разработчика сервер-приложения (Backend), которую можно использовать для создания документации в Confluence. Аналогичную структуру постановки задачи можно реализовать через инструменты документирования и тестирования API - Postman и Swagger.

Структура постановки задачи на разработку REST API метода (контракт REST API)

1. Название метода 

Название статьи в Confluence. Включает название на родном языке и endpoint.
Пример: Создание продукта - POST /product


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


3. Алгоритм работы

Пошаговое описание алгоритма работы метода, входных параметров, успешных результатов и требований к обработке ошибок.

4. Пример запроса 

4.1. Описание эндпоинта метода и базовых параметров

Включает в себя тип метода, полный URL запроса, требования к query-параметрам, заголовкам headers запроса и требования к авторизации. Может быть включена дополнительная информация по cookies.

- query-параметры: нет
- headers: 
-- content-type: application/json
- authorization: token пользователя.

4.2. Тело запроса

Пример тела запроса. Обычно в формате JSON, но может быть и в другом поддерживаемом RES API формате - например, XML.

Пример:
{
  “name”: “Салат”,
  “calories”: 200
}


5. Пример ответа

Приводится список различных примеров ответа, каждый со своим кодом и телом.

5.1. HTTP-Код ответа и описание

Успешный и ошибочные.
Пример для описанного POST:
HTTP-201 (успех, продукт создан)

5.2. Тело ответа
Приводится пример тела ответа к соответствующему коду.

Пример для описанного POST:
{
  “id”: 1,
 “name”: “Салат”,
  “calories”: 200
}


6. Для описанных JSON структур приводятся таблицы маппинга данных: JSON запроса / ответа с БД.


7. Дополнительные требования:

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


Заключение

Эта структура контракта для метода REST API. которая может быть использована разработчиками Backend для реализации метода, и разработчиками клиентов API, кто будет использовать этот REST API запрос в своём приложении.

Если все эти пункты есть в вашей постановке задачи, то вы точно ничего не упустили!

А более подробно мы разбираем как наполнять каждый из разделов постановки задачи на практической программе обучения "Дизайн REST API", разрабатывая проект API-документации с нуля.

Контакты

+7 (499) 686-15-46

*Instagram — запрещенная на территории РФ организация

Практический опыт здесь, 2021-2024

Мы используем файлы cookie, для персонализации сервисов и повышения удобства пользования сайтом. Если вы не согласны на их использование, поменяйте настройки браузера.