codeconv/API.md

#API

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

##Общие положения

• По умолчанию используем REST
• Общение между сервисами организуется через grpс. Если нужно получить какую-то информацию от внутреннего сервиса, идём в этот сервис и делаем метод для этого.
• Методы которые используются админами и методы которые используются клиентами надо разделять на 2 раздельных сервера
• Иногда может понадобится стрим данных. SSE в приоритете, но если требуется изменение свойств стрима или запросов очень много и есть возможность перевести весь фронтенд перевести на другую технологию, берём вебсокет. Возможно потом попробуем wormhole
• Роут метода должен формироваться следующим образом: /{название сущности}[/{идентификатор сущности, если работа с конкретной сущностью}]/[дополнительное указание метода, если REST метода недостаточно]

##Получение данных

Получение списка сущностей с пагинацией

• Дополнительное указание метода чаще всего нужно. Для единообразия стоит указывать getList
• REST метод GET
• Стандартные GET параметры для запроса page - указание номера страницы выборки и size - для указания размера страницы
• В ответе должны быть: массив запрашиваемых сущностей и количество сущностей по этому фильтру вообще
• Позднее будет введена логика фильтров. Как их будем передавать я пока не знаю. Явно через GET параметры, но как json или через какую-то логику саб параметров - не знаю