- Введение
- Формирование "url" запроса
- Примеры запросов по типам
- Формат ответа
1 Введение¶
| 1.1 Назначение модуля | вверх¶
- Предоставление интерфейса взаимодействия с DataCore 3;
| 1.2 Общие принципы | вверх¶
- Взаимодействие с DataCore 3 построено на шаблонах. Шаблон - универсальное представление набора данных. Шаблон может равнятся одной таблице в базе, может равнятся нескольким. Основное преимущество шаблона - он абстрагирует данные от механизма их хранения. Пример - есть шаблон "пользователь", у него есть имя и фамилия, которые хранятся в одной таблице, есть адрес, который хранится в другой таблице, но клиенту эти данные приходят одним набором.
- Шаблоны имеют свой уникальный идентификатор (номер);
- Для произведения манипуляций с данными в базе нужно отправить запрос соответствующего типа на API сервер с указанием номера шаблона и параметров запроса;
- Поддерживаються следующие операции над шаблонами котрым соответствуют типы запросов:
| операция |
тип запроса |
описание |
| создание |
POST |
в базе создаеться новая запись по указанному шаблону |
| чтение |
GET |
из базы получаем записи, либо все, либо согласно указанным условиям, по указанному шаблону |
| редактирование |
PUT |
в базе редактируется запись по указанному условию |
| замена |
PATCH |
в базе осуществляеться замена либо создание записи если она отстутсвует |
| выполнение |
MOVE |
в базе выполняеться процедура, соответствующая шаблону |
| удаление |
DELETE |
в базе удаляется запись по указанному шаблону и условию |
- К шаблонам могут быть разрешены как все типы запросов так и только некоторые;
2 Формирование "url" запроса¶
| 2.1 Структура | вверх¶
<protokol>://<host>[:<port>]/<version of api>/<template id>?token[<parameters string>]
| параметр |
присутствие |
описание |
пример |
| protokol |
обязательно |
протокол передачи данных |
http, https |
| host |
обязательно |
доменное имя или ip адрес ресурса |
localhost, 127.0.0.1 |
| port |
опционально |
порт на котором работает api, если не указан то для http по умолчанию используется 80, для https 443 |
3333, 5555 |
| version of api |
обязательно |
используется для идентификации алгоритма обработки входящих запросов |
/api.v1 |
| template id |
обязательно |
номер шаблона DataCore 3 к которому идет обращение |
/2018 |
| parameters string |
обязательно |
описывается в отдельном разделе ниже |
token=123456789&fields=name&conditions[name][equal]=234& |
| 2.2 Строка параметров | вверх¶
| 2.2.1 Формат | вверх¶
- Строка параметров состоит из пар ключ значение, в отдельных случаях у ключей может не быть значения (например
token до прохождения аутентификации);
- Разделителем между параметрами являеться знак
&;
- Значения ключей указываються без кавычек;
- Чтобы передать пробел в каком то значении его следует заменить на
+, например &conditions[name][equal]=taras+kuprunets;
- Принцип постоения сторки параметров cледующий:
token=value[&fields=name...][&conditions[fildName][conditionType]=value...][&modes=value...][&limit[offset]=0&limit[rowCount]=10]
| параметр |
присутствие |
описание |
пример |
| ?token |
обязательно |
служит для идентификации клиента, передается всегда. Если токен отсутствует (например до авторизации) передается параметр без значения |
token, token=123456789 |
| &fields |
опционально |
служит для указания имен полей шаблона по которым производится операция (чтение либо изменение) |
&fields=name&fields=surname |
| &conditions |
опционально |
cлужит для указания параметров выборки записейк к которым применяется операция |
&conditions[name][equal]=taras&conditions[surname][equal]=kuprunets |
| &modes |
опционально |
служит для указания нестандартного поведения либо расширения возможностей выполнения запроса |
&modes=testing&modes=noPrepare |
| &limit |
опционально |
служит для задания количества записей, которsе ожиаються от сервера, и номер первой записи от которой начинать отсчет |
&limit[offset]=0&limit[rowCount]=10 |
| 2.2.2 Именования полей | вверх¶
- Передаються в формате
fields=fieldMane. Если нужно передать несколько имен полей - передаеться несколько значений идентификатора fields;
- Имена полей передаються когда:
- Хотим получить не всю информацию по шаблону, а только некоторые поля. Пример, шаблон "пользователь" сотоит из 20 полей (имя, фамилия, аватар, адрес, телефон, имейл и т д), в текущем запросе нам нужно лишь имя и фамилия, тогда нужно явно передать названия этих полей;
- Нужно отредактировать заданные поля записей;
| 2.2.3 Условия | вверх¶
- Передаються в формате
conditions[fildName][conditionType]=value. Если нужно передать несколько имен полей - передаеться несколько значений идентификатора conditions;
- Служат для указания параметров по которым та или иная операция применяется к записям шаблона;
- Поддерживаються типы условий:
| тип |
значение |
пример |
| equal |
равно |
conditions[name][equal]=taras |
| notEqual |
не равно |
conditions[name][notEqual]=taras |
| greatest |
больше |
conditions[age][greatest]=30 |
| greatestEqual |
больше или равно |
conditions[age][greatestEqual]=30 |
| less |
меньше |
conditions[age][equal]=30 |
| lessEqual |
меньше или равно |
conditions[age][equal]=30 |
| isNull |
равно или не равно NULL (в зависимости от передаваемого значения) |
conditions[name][isNull]=true conditions[name][isNull]=false |
| in |
находится в перечислении, разделителем значений является запятая |
conditions[name][in]=0,1,2,3,4 |
| notIn |
не находится в перечислении, разделителем значений является запятая |
conditions[name][notIn]=0,1,2,3,4 |
| like |
содержит |
conditions[name][like]=ara |
| notLike |
не содержит |
conditions[name][notLike]=ras |
| 2.2.4 Режимы | вверх¶
- Передаются в формате
modes=value. Если нужно передать несколько режимов - передается несколько значений идентификатора modes;
- Используются если нужно задать нестандартное поведение
- На данный момент доступны следующие режимы:
| тип |
значение |
описание |
пример |
| тестовый |
testing |
вместе с данными запроса мы в ответе получаем в секции debug пакет сгенерированный для выполнения на севрере |
&modes=testing |
| не обработанный |
noPrepared |
база данных возвращает ответ в виде двух масивов - масив имен полей и масив масивов значений, сервер преобразовывает ответ в масив обектов имя поля - значение поля, если стоит режим без предварительно обработки - сервер не будет выполнять это преобразование |
&modes=noPrepared |
| 2.2.5 Сортировка| вверх¶
- Передается в формате
sort[fieldName]=sortType. Если нужно передать по нескольким полям - передается несколько значений идентификатора sort;
- Используются если нужно получить определенным образом отсортированные данные
- На данный момент доступны следующие режимы сортировки:
| тип |
значение |
пример |
| по возрастанию |
desc |
&sort[dtClient]=desc |
| по убыванию |
asc |
&sort[dtClient]=asc |
3 Примеры запросов по типам¶
| 3.1 Создание | вверх¶
- Создание записей производится с помощью метода POST
- В строке параметров должны быть переданы имена полей по которым передаються данные в теле запроса;
- Те поля, которые не упоминаються в fields, будут созданы со значениями поо умолчанию;
POST http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname
Content-Type: application/json
[
["taras", "kuprunets"],
["andrey", "sakhno"]
]
| 3.2 Чтение | вверх¶
- Чтение записей производится с помощью метода GET;
- При чтении могут передаваться лимиты в строке параметров если лимиты не были переданы вернется максимально разрешенное количествоо записей. Чтобы удостоверится что выбраны все записи нужно сверить количество зписей со значением полея
rowCount в метаданных пакета. Если оно больше чем получено значений необходимо віполнить еще один запрос но уже с указанием лимитов.
- При чтении могут передаваться условия выборки в строке параметров;
GET http://localhost:8081/api.v1/2018?token=123456789
| 3.3 Изменение | вверх¶
- Изменение записей производиться с помощью метода PUT;
- В строке параметров необходимо передать имена полей которые подлежать изменению;
- В теле запроса необхдимо передать значения полей выдерживая порядок указания имен полей в строке параметров.
- При изменении следует указать условия по которым будут однозначно идентифицированы записи которые подлежат изменению, если условия указаны не будут - произведется изменение всех записей указанного шаблона;
PUT http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname&conditions[objectId][equal]=1
Content-Type: application/json
[
["taras", "kuprunets"]
]
| 3.4 Замена | вверх¶
- Замена записей производиться с помощью метода PATCH;
- В строке параметров необходимо передать имена полей которые подлежать замене таким же образом следует передать название поля ключа для идентификации;
- В теле запроса необхдимо передать значения полей выдерживая порядок указания имен полей в строке параметров а так же значение ключей.
PATCH http://localhost:8081/api.v1/2018?token=123456789&fields=name&fields=surname
Content-Type: application/json
[
["taras", "kuprunets"],
["andrey", "sakhno"]
]
| 3.5 Удаление | вверх¶
- Удаление записей производиться с помощью метода DELETE;
- При elfktybb следует указать условия по которым будут однозначно идентифицированы записи которые подлежат удалению, если условия указаны не будут - произведется удаление всех записей указанного шаблона;
DELETE http://localhost:8081/api.v1/2018?token=123456789&conditions[objectId][equal]=100
| 3.6 Выполнение | вверх¶
- Существуют операции которые выходят за рамки простого создания/редактирования/удаления данных, к этим операциям можно отнести процес авторизации, сложных добавлений данных или комплексных созданий записей, требующих предварительной обработки. Для этих целей предусмотрен специальный механизм который позволяет обратится к шаблону как к функции, дав команду на ее выполнение.
- Выполнение шаблонов производиться с помощью метода MOVE;
- В теле запроса необхдимо передать значения входных параметров, какие конкретно параметры подлежат передаче зависит от конретного шаблона и будут описаны в отдельных документах, которые будут описывать конкретные раелизации API.
MOVE http://localhost:8081/api.v1/2018?token=123456789
Content-Type: application/json
[
["firstParam", "secondParam"]
]
4 Формат ответа¶
| 4.1 Структура | вверх¶
HTTP/1.1 200 Ok
Content-Type: application/json
{
"data": [
{
"metadata": {
"templateId": number,
"rowCount": number
},
"data": {
"fild1": "value1",
...
"fildN": "valueN"
}
}, {
"metadata": {
"templateId": number,
"rowCount": number
},
"data": {
"fild1": "value1",
...
"fildN": "valueN"
}
}
],
"debug"?: {
"package": "JSONString"
}
}