Описать API (набор методов) можно разными способами: с помощью специальных инструментов (swagger, api blueprint) или самостоятельно.

Самое главное, чтобы ваше описание API отражало следующие свойства.

  1. Описание запроса
  2. Тип HTTP метода
  3. Эндпоинт
  4. headers (заголовки)
  5. Входные и выходные параметры для запроса
  6. Примеры запроса и ответа

Можно использовать такой шаблон:

[HTTP-метод] [Endpoint]

Описание: [Краткое описание функционала]

Headers/Заголовки:

Название Описание
Authorization Bearer [токен доступа]
Content-Type application/json
…

Параметры запроса:

Название Тип Обязательный Описание
…

Параметры ответа: