Регламент REST API черновик

restapi.md

Декларация общих правил реализации REST API (Черновик)

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

1. Свойства сущностей с точки зрения нейминга и типов данных должны быть идентичны по всему проекту.
2. В dev контуре проверка CORS должна быть отключена.
3. Коды ответа регламентированы списком кодов состояния http и должны логически соответствовать состоянию приложения
4. Коды ответа возвращаются и на уровне http, и на уровне response body.

Стандартная структура ответа(response) сервиса

{
    code: 200, //http код ответа
    message: "ok",//человекочитаемое сообщение об ошибке/успехе
    payload: {} //основная информация об возвращаемая сервисом в рамках запроса.Объект
}

Список сущностей

Параметры запроса которые должны быть реализованы: limit, offset Фильтры запроса(пример user_type) должно быть объявлены на равне с limit/offset, то есть должны быть такими же параметрами

GET /entity_name?limit=10&offset=0&user_type=manager

{
	code: 200,
    message: "ok",
    payload: {
        count: 27,//количество записей в листе
        limit: 10,//выбранный лимит записей
        offset: 10,// выбранный отступ по записям
        rows: [ //все записи списка
			...{...} 
		]
	} 
}

Запрос за детальной информацией сущности

GET /entity_name/{id}

{
	code: 200,
	message: "ok",
	payload: {
		id,
		... 
	}
}

Запрос на создание сущности

POST /entity_name

{
	code: 201,
	message: "ok",
	payload: {
		id,
		... 
	}
}

Запрос на редактирование сущности

PUT /entity_name/{id}

{
	code: 201,
	message: "ok",
	payload: {
		id,
		... 
	}
}

Запрос на удаление сущности

DELETE /entity_name/{id}

{
	code: 200,
	message: "ok"
}

Сортировка

Варианты сортировки

Синтаксис	Результат
sort=id или sort=+id	order by id asc
sort=-id	order by id desc
sort=status,-id	order by status asc, id desc