Форматы передачи атрибутов и их значений в методах 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=ca36dd26-1296-42ae-849b-5d9e63987fc0

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

{"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=e00c8761-b105-4c2b-a86c-f7fe20cff9b3

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

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

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

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

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

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

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

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

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

http://localhost:8888/services/rest/create/team?accessKey=e00c8761-b105-4c2b-a86c-f7fe20cff9b3&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):

http://localhost:8888/services/rest/create/team/{"title":"new","metaClass":"team$ATTeamCase"}?accessKey=e00c8761-b105-4c2b-a86c-f7fe20cff9b3

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

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

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

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

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

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):

http://192.168.225.145:8888/sd/services/rest/create/comment/{"source":"serviceCall$155611805","text":"Новый комментарий","creationDate":"2020.01.02 06:07:59 %2B0500"}?accessKey=eebd1cdf-1ff7-495c-bc4c-4288af18b7b4

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

http://192.168.225.145:8888/sd/services/rest/create/comment?accessKey=eebd1cdf-1ff7-495c-bc4c-4288af18b7b4

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

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

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

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

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

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

Гиперссылка

Значение атрибута типа "Гиперссылка" передается как объект или строка.

Для передачи гиперссылки в качестве значения изменяемого атрибута, в теле REST запроса достаточно указать ее в html виде.

<a href=\"https://test.local/\">test</a>

Файл

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

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

Значение атрибута типа "Временной интервал" передается, как объект или количество миллисекунд.

Логический

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