Настройка точек доступа API

Основные настройки точки доступа API

Destination structure

Целевая структура. К данным в ней настраивается доступ.

Name

Название. Отображается в списке всех точек доступа API.

Address

Адрес. Также позволяет перечислить список параметров, который будут приходить в запросе. Эти параметры будут доступны в шаблонизаторе настроек фильтров.

Пример заполнения поля Address:

https://directual.com/good/api/v5/data/Books/getBooks?author=

,где getBooks — идентификатор точки доступа в адресе, ? — обозначение начала параметров, author — параметр, доступный в шаблонизаторе. Подробнее в о параметрах далее.

Filters

Настройка фильтров позволяет отфильтровать объекты в результирующей выдаче. По клику на поле задаётся одно или несколько условий, по которым отбираются объекты для ответа. В фильтрах доступно использование шаблонизированных переменных и параметров из запроса.

В фильтрах можно обращаться к полям слинкованных объектов, но в таком случае целевая структура данных должна быть проиндексирована, и в индексах должны быть перечислены поля, по которым будет осуществляться фильтрация. Подробнее об индексировании.

Платформа проставляет индексы автоматически в момент установки фильтров. Но, поскольку доступно удаление настроек самостоятельно, стоит проверить структуру вручную при обнаружении некорректного поведения.

При фильтрации по слинкованным полям обязательно должна быть включена индексация

Параметры из запроса. HttpRequest

Одним из параметров является httpRequest. Он позволяет использовать значения для сравнения, полученные от пользователя из фронтовой части приложения.

Например, получим список книг структуры Books, у которых значение поля author берётся из параметра, передаваемого в URL:

{{HttpRequest.author}} — это шаблон, выбранный в Expression helper, в который будет подставляться значение из переменной author в URL. Для каждого объекта структуры Books будет проверено условие: равно ли значение поля author значению параметра author, и, если да, то объект попадёт в результирующую выдачу.

Если значение поля author=Tolstoy, то URL запроса будет выглядеть следующим образом:

https://directual.com/good/api/v5/data/Books/Books?author=Tolstoy

Coding mode (Raw mode) в фильтрах

Условия в фильтре можно писать в expert-mode, с помощью кода следующего вида:

[
{
"exp": "all", // “all” — эквивалент “и”
"filters": [
{
"exp": "==", // оператор сравнения
"field": "number1", // поле, которое сравниваем
"value": "1", // со значением (можно использовать шаблонизатор и структуры {{WebUser}}, {{HttpRequest}}
"isExp": false // флаг выполнения value как JS-выражения
},
{
"exp": "!=",
"field": "number1",
"value": "2",
"isExp": false
},
{
"exp": "all",
"filters": [
{
"exp": "any", // “any” — эквивалент “или”
"filters": [
{
"exp": "==",
"field": "number1",
"value": "{{HttpRequest.email}}",
"isExp": false
},
{
"exp": "==",
“field": "string2",
"value": "дело1",
"isExp": false
}
]
}
]
}
]
}
]

Order

Для данных в ответе на запрос можно задать сортировку. Для этого нужно выбрать поле, по которому сортировать, и направление сортировки: по возрастанию (Ascending) или по убыванию (Descending).

Интересно!

Если вы хотите использовать один SL, но задействовать другие параметры сортировки, в запросе можно дописать вашу потребность в виде: YourField,desc,YourField2,asc

{{YourDomain}}/good/api/v5/data/111/111?appID={{appID}}&sessionID={{sessionID}}&sort=YourField,desc,YourField2,asc

При этом сортировка пройдёт сначала по полю YourField, а затем по YourField2

Для сохранения API Endpoint нужно обязательно указать хотя бы один SL и список полей для чтения

Просмотрщик результатов запроса

Справа от поля "Путь" есть две кнопки:

  • Скопировать ссылку — копирует адрес в буфер обмена (например, для просмотра из стороннего приложения, такого как Postman).

  • "Глаз" — инструмент для просмотра SL.

Это полноценный просмотрщик ответа на запрос к вашей точки доступа. В зависимости от настройки SL, вам может понадобиться ввести имя пользователя для просмотра ответа. По умолчанию, в фильтре SL установлено значение "id is not null". Это означает, что пользователь должен быть в списке системной структуры WebUser. Если такого пользователя в структуре нет, то вернётся ответ как на скриншоте ниже.

Для быстрого просмотра, пользователя можно создать здесь же (галочка "автоматически создать пользователя").

Настройки SL

Для того, чтобы обратиться по заданному адресу API и получить в ответ данные, нужно настроить хотя бы один слой защиты.

Условия доступа SL

В запросе к SL может передаваться параметр sessionID, по которому автоматически находится пользователь из структуры webUser, от которого этот запрос пришёл. Благодаря этому можно настроить условия доступа к данным для каждого SL. Мы выбираем значения параметров пользователя для этого слоя.

Например, разрешим просмотр данных о книгах (название книги и автор) только пользователям с ролью admin:

Пользователям, которые соответствуют условию, будет разрешен доступ на чтение перечисленных полей.

Важно!

Для разных SL можно задавать разные наборы данных на запись и чтение. Проверка условий SL производится сверху вниз: первое подходящее отрабатывает, и дальше проверка не идёт.

Чтение данных

Для чтения данных отправляется GET запрос на заданный адрес. В запросе могут быть переданы параметры для использования, например, в фильтрах. Помимо этого могут быть переданы параметры пагинации:

  • pageSize — количество объектов на странице для создания постраничного списка

  • page — номер выдаваемой страницы Для чтения доступны не только данные объектов выдачи, но и данные слинкованных объектов по link и arrayLink. В настройках полей на чтение можно "проваливаться" на любой уровень вложенности.

Пример GET запроса:

https://directual.com/good/api/v5/data/Books/getBooks?appID=appID&sessionID=sessionID

Ключ

Тип

Значение

Описание

appID

String

True

Открытый ключ приложения

sessionID

String

True

ID сессии пользователя

Ответ:

{
"payload": [
{
"name": "Anna Karenina",
"author": "Leo Tolstoy"
},
{
"name": "The Death of Ivan Ilyich",
"author": "Leo Tolstoy"
},
{
"name": "War and Peace",
"author": "Leo Tolstoy"
}
],
"pageInfo": {
"currentPage": 0,
"pageSize": 30,
"totalPage": 1,
"tableSize": 3,
"currentPageSize": 3
},
"status": "OK"
}

Запись данных

Для записи отправляется POST запрос. В запросе передаются обязательные параметры appID, secretID.

Пример POST запроса:

https://directual.com/good/api/v5/data/Books/getBooks?appID=appID&sessionID=sessionID

В теле запроса отправляются данные в JSON формате:

[
{
"name":"Москва",
"author":"Игорь Петров",
"year":"1963"
},
{
"name":"Архипелаг ГУЛАГ",
"author":"Александр Солженицин",
"year":"1973"
}
]

В ответе возвращаются данные созданных объектов. Здесь будут возвращены те параметры объектов, которые указаны в наборе полей на чтение (если значения таких полей есть).

Режим запуска сценариев

Помимо записи данных объектов можно запускать обработку этих объектов сценариями. Для этого в SL нужно выбрать список сценариев для запуска. Это делается в настройках Run scenarios in sync mode. В списке сценариев для запуска будут отображены только те запущенные сценарии, которые принимают на вход объект заданного в настройках API Endpoint типа.

Объекты будут попадать в сценарий, указанный в SL вне зависимости от условия его запуска, то есть будут форсировать его.

Дополнительные настройки

В разделе Settings можно заполнить дополнительные настройки: Описание, настройка индекса и CORS.

  • Настройка Enable CORS управляет разрешением использовать кросс-доменные запросы.

  • Настройка Use Index:

Use Index работает только для HBase

В случае использования HBase инструмент работает следующим образом: Если используется фильтр по слинкованным полям, то работает обычный поиск по HBase. При необходимости использовать быстрый поиск нужно указать индексацию (в настройках структуры включить индексацию и в настройках SL включить Use Index = true).

Если в фильтре используется обращение к полям слинкованного объекта (через точку), то по умолчанию будет использоваться поиск по индексу, но, как и в случае выше, поля должны быть проиндексированы в структуре.