Форматы передачи атрибутов и их значений в методах REST API

В методы create, create-m2m, edit, edit-m2m, find атрибуты и их значения передаются унифицировано в различных форматах.

В разделе приведен полный список поддерживаемых форматов передачи атрибутов и их значений. Другие форматы передачи, например, с использованием multipart/form-data, в методах create, create-m2m, edit, edit-m2m, find не поддерживаются.

В теле POST-запроса в формате JSON

Предпочтительный формат передачи атрибутов и их значений, обеспечивающий полное соответствие протоколу HTTP/1.1.

Метод вызова: POST.

Формат адреса запроса: "/<действие>/<UUID или FQN>", где:

  • <действие> — один из методов: create, create-m2m, edit, edit-m2m, find;
  • <UUID или FQN> — уникальный идентификатор объекта или FQN класса/типа объекта, в зависимости от используемого метода.

Коды атрибутов и их значения передаются в виде JSON-объекта внутри тела POST-запроса.

Пример адреса запроса (URL):

http://localhost:8888/services/rest/create/team?accessKey=<accessKey.UUID>

Пример тела запроса:

{"title":"new","metaClass":"team$ATTeamCase"}

В строке запроса в формате Base64 URL

Формат имеет ограничение. Рекомендуется передавать атрибуты и их значения в теле POST-запроса в формате JSON.

Методы вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера.

Формат адреса запроса: "/<действие>/<UUID или FQN>/{attributes}", где:

  • <действие> — один из методов: create, create-m2m, edit, edit-m2m, find;

  • <UUID или FQN> — уникальный идентификатор объекта или FQN класса/типа объекта, в зависимости от используемого метода;

  • {attributes} — коды атрибутов и их значения в виде JSON-объекта, который закодирован в Base64 URL. В начало строки, полученной после кодирования, необходимо добавить "40x".

    Форматом Base64 URL признается кодирование URL-адресов, при котором символы + и / заменяются, соответственно, на - и _ (см. документацию).

Пример адреса запроса (URL):

http://localhost:8888/services/rest/create/team/40xeyJtZXRhQ2xhc3MiOiJmaWxlIn0=?accessKey=<accessKey.UUID>

Ограничение:

  • Для передачи используется URL-строка, которая во многих браузерах ограничена 2000 символами. Строки, большие по длине, обрезаются.

В строке запроса через параметры

Формат имеет ограничения. Рекомендуется передавать атрибуты и их значения в теле POST-запроса в формате JSON.

Методы вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера.

Формат адреса запроса: "/<действие>/<UUID или FQN>", где:

  • <действие> — один из методов: create, create-m2m, edit, edit-m2m, find;
  • <UUID или FQN> — уникальный идентификатор объекта или FQN класса/типа объекта, в зависимости от используемого метода.

Коды атрибутов и их значения передаются в виде параметров в строке запроса.

Пример адреса запроса (URL):

https://localhost:8888/services/rest/create/team?accessKey=<accessKey.UUID>&title=new&metaClass=team$ATTeamCase

Ограничения:

В строке запроса в формате JSON без кодирования

Формат имеет ограничения. Рекомендуется передавать атрибуты и их значения в теле POST-запроса в формате JSON.

Методы вызова: POST, GET. Рекомендуется использовать POST во избежание проблем с лимитами на стороне веб-сервера.

Формат адреса запроса: "/<действие>/<UUID или FQN>/{attributes}", где:

  • <действие> — один из методов: create, create-m2m, edit, edit-m2m, find;
  • <UUID или FQN> — уникальный идентификатор объекта или FQN класса/типа объекта, в зависимости от используемого метода;
  • {attributes} — коды атрибутов и их значения в виде JSON-объекта без кодирования.

Пример адреса запроса (URL):

https://localhost:8888/services/rest/create/team/{"title":"new","metaClass":"team$ATTeamCase"}?accessKey=<accessKey.UUID>

Ограничения:

Для работы с данным форматом при установке системы необходимо использовать дистрибутив Tomcat, адаптированный для приложения SMP. Или в настройках Tomcat необходимо разрешить использование символов — добавить в файл server.xml в блок <Connector> свойство relaxedPathChars="&quot;}{". После настройки Tomcat требуется перезапуск системы.

Особенности передачи значений отдельных типов атрибутов

Агрегирующий атрибут

Редактирование составных частей агрегирующего атрибута необходимо выполнять только через обращение к самому агрегирующему атрибуту, в противном случае корректная работа не гарантируется. Обращение к составным частям агрегирующего атрибута и их отдельное редактирование может привести к рассинхронизации значений составных частей агрегирующего атрибута.

Особенности аналогичны скриптовому API, см. Редактирование значения агрегирующего атрибута.

Временной интервал

Для значения атрибута типа "Временной интервал" поддерживается несколько форматов передачи.

Основной формат передачи — JSON-объект, он поддерживается методами создания (create, create-m2m), изменения (edit, edit-m2m) и поиска (find):

{

"length": <длина интервала в указанной единице измерения>,

"interval": "SECOND"

}

В качестве единицы измерения могут использоваться:

  • SECOND — для секунд;
  • MINUTE — для минут;
  • HOUR — для часов;
  • DAY — для дней;
  • WEEK — для недель.

Вспомогательный формат передачи — количество миллисекунд, он поддерживается только методами создания (create, create-m2m) и изменения (edit, edit-m2m).

При использовании методов REST API ожидается объект IDateTimeInterval или количество миллисекунд.

Гиперссылка

Для значения атрибута типа "Гиперссылка" поддерживается несколько форматов передачи.

Основной формат передачи — JSON-объект, он поддерживается методами создания (create, create-m2m), изменения (edit, edit-m2m) и поиска (find):

{

"text": "текст ссылки",

"url": "https://example.local/"

}

Вспомогательный формат передачи — в виде HTML, он поддерживается только методами создания (create, create-m2m) и изменения (edit, edit-m2m):

<a href="https://example.local/">текст ссылки</a>

Дата и Дата/время

Значение атрибута типа "Дата/время" передается в одном из форматов: "yyyy.MM.dd", "yyyy.MM.dd HH:mm", "yyyy.MM.dd HH:mm:ss" или "yyyy.MM.dd HH:mm:ss z" (с часовым поясом):

api.rest.edit(subject, ['dateTimeAttrCode' : '2020.08.25 14:43'], api.auth.getAccessKey('username'))

Значение атрибута типа "Дата" передается в формате "yyyy.MM.dd":

api.rest.edit(subject, ['dateTimeAttrCode' : '2020.08.25'], api.auth.getAccessKey('username'))

Пример 1. Добавление комментария с указанием часового пояса (атрибут creationDate) в GET-запросе в виде Json-объекта (знак + передается как %2B в формате urlencode):

https://192.168.225.145:8888/sd/services/rest/create/comment/{"source":"serviceCall$155611805","text":"Новый комментарий","creationDate":"2020.01.02 06:07:59 %2B0500"}?accessKey=<accessKey.UUID>

Пример 2. Добавление комментария с указанием часового пояса (атрибут creationDate) в теле POST-запроса:

https://192.168.225.145:8888/sd/services/rest/create/comment?accessKey=<accessKey.UUID>

В тело запроса: {"source":"serviceCall$155611805","creationDate":"2020.01.02 06:07:59 +0500","text":"Новый комментарий"}

Если часовой пояс не указан в параметре запроса, система обработает этот запрос в своем часовом поясе.

В случае поиска (через метод find) по атрибуту типа "Дата/время" будут возвращены только объекты, в которых значение полностью совпадает с переданным. Для получения объекта, значение которого хранится с точностью до миллисекунд, необходимо передать дату и время с секундами и миллисекундами — yyyy.MM.dd HH:mm:ss.SSS, пример, 2020.08.25 14:43:10.816.

Логический

Значение атрибута типа "Логический" передается, как true или false.

Ссылочные атрибуты

Значение атрибута типа "Агрегирующий атрибут", "Обратная ссылка", "Ссылка на бизнес-объект" и "Элемент справочника" передается как объект или идентификатор.

При использовании методов REST API ожидается объект IUUIDIdentifiable или его идентификатор.

Значение атрибута типа "Набор ссылок на бизнес-объекты", "Набор типов класса" и "Набор элементов справочника" передается, как коллекция объектов или идентификаторов:

['attrCode':['attrValue1','attrValue2']]

При использовании методов REST API ожидается коллекция объектов IUUIDIdentifiable или идентификаторов объектов — ['attrCode':['attrValue1','attrValue2']].

Файл

Значение атрибута типа "Файл" передается как коллекция идентификаторов файлов.

При использовании методов REST API ожидается массив объектов IUUIDIdentifiable или их идентификаторов, подобно ссылочным атрибутам.

Если файл отсутствует в системе, то для его прикрепления к объекту необходимо использовать метод add-file.