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

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

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

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

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

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

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

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

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

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

Пример: 
POST https://g-food.com/api/public/1.0/product 

- 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-документации с нуля.