Статьи

Документация

Дополнительно

Автоматические ресурсы

Добавление схемы в качестве ресурса хоста создаёт автоматический ресурс для доступа к ней:

    // '/' в конце обязателен
    serv.addResourceHandler("/objects/", _objects);

Общий API объектов

Типы значений описаны в модули БД

Система использует код ответа 403 FORBIDDEN если действие не позволено текущему пользователю

Система использует код ответа 404 NOT FOUND если ресурс не найден

Система отвечает в формате JSON. Ответ может содержать следующие поля:

  • OK - успешность выполнения команды (содержится в любом ответе)
  • error - ключевая ошибка, не позволившая выполнить команду
  • errors - список возникших ошибок и отладочная информация

API списков

Адрес /list - адрес доступа к списку ресурсов (основному или вложенному в другой ресурс (Например: /api/v1/users, /api/v1/app/id123/issues)

GET /list , GET /list/all - возвращает список доступных объектов PUT /list , PUT /list/all - обновляет данные всех объектов в списке DELETE /list , DELETE /list/all - удаляет все объекты списка POST /list - создаёт новый объект, используя данные запроса, возвращает новый объект

API объектов

Адрес /objects - адрес доступа к набору объектов

GET /objects/id[%OID%] - возвращает объект по OID GET /objects/named-[%NAME%] - возвращает объект по ассоциированному имени

PUT /objects/id[%OID%] - обновляет данные объекта по OID, возвращает новые данные объекта PUT /objects/named-[%NAME%] - обновляет данные объекта по ассоциированному имени, возвращает новые данные объекта

DELETE /objects/id[%OID%] - удаляет объект по OID DELETE /objects/named-[%NAME%] - удаляет объект по ассоциированному имени

API свойств

Адрес /object - адрес доступа к индивидуальному объекту (/users/id123, /files/named-filename)

GET /object/[%PROPNAME%] - получает данные свойства

  • file - возвращает содержимое файла
  • object - возвращает данные объекта
  • set - возвращает список объектов
  • array - получает все элементы массива

PUT /object/[%PROPNAME%] - обновляет данные свойства

  • file - загружает новый файл (используется первый загруженный файл или весь запрос при одиночной загрузке файла)
  • object - обновляет данные объекта (при обновлении поля __oid пытается связать с другим объектом)
  • set - обновляет список объектов
  • array - перезаписывает массив (читает данные из значения %PROPNAME%

POST /object/[%PROPNAME%] - создаёт объект для свойства

  • file - не доступно
  • reference object - создаст новый объект, создаст ссылку на объект для свойства
  • object - создаст новый объект, вложенный в текущий объект
  • set - создаст новый объект, добавит его в список
  • array - дописывает элементы в конец массива

DELETE /object/[%PROPNAME%] - удаляет свойство

  • file - удаляет вложенный файл (если возможно)
  • reference object - удаляет связь с объектом, не удаляет объект
  • object - удаляет объект
  • reference set - удаляет список, не удаляет хранимые в нём объекты
  • set - удаляет список вместе с объектами
  • array - удаляет весь массив

API индексированых списков

Эти свойства определены у каждого объекта в примере:

  • protected (number) __oid - ID объекта
  • required auto (string) name - ассоциированное с объектом имя

Адрес /list - адрес доступа к списку ресурсов (основному или вложенному в другой ресурс (Например: /api/v1/users, /api/v1/app/id123/issues)

GET /list/select/{%INDEX_NAME%}/{%SELECT_STMT%} - выбор по значениям свойства GET /list/order/{%INDEX_NAME%}/{%ORDER_STMT%} - упорядочивание по значению свойства GET /list/first/{%INDEX_NAME%}/[count=1] - выбор N первых элементов по значению свойства GET /list/last/{%INDEX_NAME%}/[count=1] - выбор N последних элементов по значению свойства .../offset/1 - смещение после сортировки или ограничения

SELECT_STMT := / [{%SELECT_MODE%}=eq] / value1 [ / value2] / limit - выбор по значениям

SELECT_MODE - режим сравнения:

  • lt - less then - меньше чем (одно значение)
  • le - less or equal - меньше или равно (одно значение)
  • eq - equal - равно (одно значение), для полнотекстового поля выполняет полнотекстовый поиск
  • ge - greather or equal - больше или равно (одно значение)
  • gt - greather then - больше чем (одно значение)
  • bw - between - между, невключительно (два значения)
  • be - between|equals - между (включительно) (два значения)
  • value1, value2 - значения для сравнения
  • limit - максимальный размер выборки

ORDER_STMT := / [{%ORDER_MODE%}=asc] / limit - упорядочивание

ORDER_MODE - режим упорядочивания

  • asc - по возрастанию
  • desc - по убыванию
  • limit - максимальный размер выборки

Порядок выполнения запросов:

  1. SELECT во порядке возрастания размера выборки
  2. ORDER (в запросе допускается только один ORDER, используется последний)
  3. RESOLVE преобразует список объектов в непосредственно объекты, применяются ограничения pageFrom и pageCount

Запросы полей

Запросы полей оформляются в виде Serenity Query:

Включение и исключение полей схемы контролируется значениями exclude и fields

fields - список полей для включения в ответ. Если список не указан, интерпретируется как $defs

exclude - список полей для исключения из запроса. Работает после того, как поле проверено на включение по списку включения (приоритет исключения выше приоритета включения)

Поля определяются по токену, соответствующему имени поля.

...?(fields:name1,name2) - простое раскрытие имён ...?(fields:(list1:field1,field2;list2(list3:field3;field4))) - с вложенными полями

Представление с подполями:

fields (
    name;
    tags;
    issues: $basics, content;
    articles (
        name;
        content: type, size;
    )
)

Специальные значения:

  • $all - раскрывает ве поля
  • $files - раскрывает файловые поля
  • $sets - раскрывает наборы
  • $objects, $objs - раскрывает вложенные объекты
  • $arrays - раскрывает массивы
  • $defaults, $defs - режим по умолчанию, раскрывает только простые поля
  • $basics - элементарные поля (не Extra и Data)
  • $ids - для объектов и наборов вместо содержимого возвращает только идентификаторы

ContinueToken:

Применяется для перебора объектов с помощью soft limit, используется через Serenity Query формат ...?(fields:<поля для раскрытия>;begin:<код начала>)

Примеры кодов начала:

  • (begin:10) - шаг по 10 объектов по полю __oid по возрастанию
  • (begin:__oid) - шаг по умолчанию по полю __oid по возрастанию
  • (begin:index) - шаг по умолчанию по полю index по возрастанию
  • (begin:10,desc) - шаг по 10 по полю __oid по убыванию
  • (begin:index,10,desc) - шаг по 10 по полю index по убыванию

В результате система возвращает поле cursor с полями:

  • total - всего элементов в наборе
  • count - элементов в текущем результате
  • start - начальный элемент в текущем результате
  • end - конечный элемент в текущем результате
  • next - токен для следующей страницы (если есть)
  • prev - токен для предыдущей страницы (если есть)

Токен используется с помощью поля (continue:).

Примеры:

Выбор объекта с минимальным значением counter / objects / first / counter/ objects / order / counter / asc / 1/ objects / order / counter / asc ? pageCount = 1

выбор 10 последних объектов по значению counter / objects / last / counter / 10/ objects / order / counter / desc / 10/ objects / order / counter / desc ? pageCount = 10

выбор 10 последних объектов по значению counter начиная с пятого / objects / last / counter / 10 ? pageFrom = 5

выбор объектов со значением counter = 2 / objects / select / counter / 2/ objects / select / counter / eq / 2

выбор максимум 10 объектов со значением counter между 10 и 20 включительно / objects / select / counter / be / 10 / 20 / 10

выбор объектов со значением counter между 10 и 20 невключительно и значением value больше 2, упорядоченные по значению priority по убыванию / objects / select / counter / bw / 10 / 20 / select / value / gt / 2 / order / priority / desc