Начало работы с REST

В этом разделе представлено практическое руководство по началу работы с универсальным REST API.

Предположим, что мы хотим получить в приложении информацию о заказах через REST API.

Для начала добавьте REST в свой проект как описано в разделе Установка и запустите приложение.

Разрешение пользовательского доступа через REST

Взаимодействие с приложением через REST API всегда происходит в контексте конкретного пользователя. Поэтому нам будет нужно предоставить пользователю возможность доступа к приложению через API.

Выбранному пользователю необходимо назначить предопределенную роль REST: minimal access (с кодом rest-minimal). Пользователь admin уже обладает всеми необходимыми разрешениями благодаря роли system-full-access.

Аутентификация для API

В следующем примере для взаимодействия с REST API мы используем инструмент командной строки curl.

Перед загрузкой данных или отправкой данных в API необходимо выполнить логин или запрос Authentication request. Используйте следующую команду cURL для выполнения запроса:

curl -X POST http://localhost:8080/oauth/token \
   --basic --user client:secret \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=password&username=admin&password=admin"

В Windows удалите символы \ и вводите команду одной строкой.

HTTP 200 означает успешный ответ, который содержит документ JSON с информацией о результате запроса аутентификации:

HTTP/1.1 200

{
  "access_token": "zmSIwB4_9he68yrNsHC5N1agktA",
  "token_type": "bearer",
  "refresh_token": "Tm3_v0T-eeYS6URZgoi4e_r-ub8",
  "expires_in": 31535999,
  "scope": "rest-api",
  "OAuth2.SESSION_ID": "5C46CDF266E8C8C15372887830B74F59"
}

Атрибут access_token — это токен, который можно использовать для дальнейших запросов в заголовке Authorization. Он действует как временные учетные данные, которые предоставляют вам доступ к приложению от имени пользователя.

Запрос списка сущностей

С токеном доступа вы можете использовать операции (endpoints) REST API для загрузки списка пользователей. Замените <access_token> значением, полученным на предыдущем шаге. Мы извлечем всех пользователей в приложении через Entities API:

curl -X GET http://localhost:8080/rest/entities/User \
    -H "Authorization: Bearer <access_token>"

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

HTTP/1.1 200

[
  {
    "_entityName": "User",
    "_instanceName": "  [admin]",
    "id": "60885987-1b61-4247-94c7-dff348347f93",
    "version": 1,
    "active": true,
    "username": "admin"
  }
]