Skip to content

Instantly share code, notes, and snippets.

@mes01
Last active March 7, 2024 09:12
Show Gist options
  • Save mes01/8806b531150cc0bbe0a71559dc08fd99 to your computer and use it in GitHub Desktop.
Save mes01/8806b531150cc0bbe0a71559dc08fd99 to your computer and use it in GitHub Desktop.
Регламент REST API черновик

Декларация общих правил реализации 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment