Общий синтаксис

Содержание

Общий синтаксис#

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

Структура запроса#

Запрос API состоит из следующих элементов:

<method> <URI>[<query>]
   [<headers>]
   [{<body>}]

<method> – указывает, какого рода действие нужно выполнить с ресурсом:
- GET – получение данных об объекте (ресурсе) или данных в виде списка объектов по указанному URI.
- POST – создание нового объекта или выполнение команды контроллера.
- PUT и PATCH – обновление указанного объекта.
- DELETE – удаление объекта.
<URI> – указывает на конкретный ресурс, с которым необходимо выполнить действие. При необходимости к URI добавляют параметры запроса (query string).
<headers> – заголовки HTTP содержат дополнительные метаданные запроса, такие как:
- тип контента;
- параметры авторизации;
- язык;
- формат.
<body> – тело запроса содержит данные, которые нужно передать на сервер.

Например, в результате следующего запроса будет создан пользователь с именем <your_username> и паролем <your_password>:

POST https://<address>/api/v2/users/ HTTP/1.1
Content-Type: application/json
Authorization: Bearer <your_token>

   {
      "username": "<your_username>",
      "password": "<your_password>"
   }

Здесь:

POST – указывает на то, что новый объект должен быть создан на сервере.
https://<address>/api/v2/users/ – указывает на конкретный ресурс, к которому обращается запрос. В данном случае запрос отправляется к ресурсу users в рамках API.
HTTP/1.1 – название и версия протокола HTTP, используемые для связи между клиентом и сервером.
Content-Type: application/json – заголовок, указывающий на то, что данные отправляются в формате JSON.
Authorization: Bearer <your_token> – заголовок, указывающий на использование bearer token для авторизации и содержащий сам токен.

Структура ответа#

Ответ на HTTP-запрос состоит из следующих частей:

<status_line>
   [<headers>]
   [{<body>}]

<status_line> – статусная строка. Содержит название и номер версии используемого протокола, код статуса и его краткое описание. Самыми распространенными кодами статуса являются:
- 200 – запрос успешно выполнен.
- 201 – в результате запроса был создан новый объект.
- 202 – запрос получен, но еще не обработан.
- 301 – URL запрошенного ресурса был изменен навсегда. Новый URL будет указан в ответе.
- 302 – URL запрошенного ресурса был временно изменен.
- 400 – запрос был сформирован с ошибками.
- 403 – нет прав доступа к запрошенному ресурсу.
- 404 – запрошенный ресурс не существует.
- 500 – на сервере произошла ошибка, в результате которой он не может успешно обработать запрос.
<headers> – заголовки, содержащие сведения об ответе. Могут включать информацию о типе содержимого, кешировании, дате и времени, сервере, длине тела ответа и другие сведения.
<body> – тело ответа, содержащее данные, отправленные от сервера к клиенту в ответ на запрос. Может содержать данные различных типов, например, текст, JSON и так далее, в зависимости от запроса и целей обмена информацией.

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

HTTP/1.1 201 Created
Content-Type: application/json

   {
   "id": 7,
   "type": "user",
   "url": "/api/v2/users/7/",
   "related": {
      "named_url": "/api/v2/users/<your_username>/",
      "teams": "/api/v2/users/7/teams/",
      "organizations": "/api/v2/users/7/organizations/",
      "admin_of_organizations": "/api/v2/users/7/admin_of_organizations/",
      "projects": "/api/v2/users/7/projects/",
      "credentials": "/api/v2/users/7/credentials/",
      "roles": "/api/v2/users/7/roles/",
      "activity_stream": "/api/v2/users/7/activity_stream/",
      "access_list": "/api/v2/users/7/access_list/",
      "tokens": "/api/v2/users/7/tokens/",
      "authorized_tokens": "/api/v2/users/7/authorized_tokens/",
      "personal_tokens": "/api/v2/users/7/personal_tokens/"
   },
   "summary_fields": {
      "user_capabilities": {
            "edit": true,
            "delete": true
      }
   },
   "created": "2024-03-28T22:53:18.939698Z",
   "modified": null,
   "username": "<your_username>",
   "first_name": "",
   "last_name": "",
   "email": "",
   "is_superuser": false,
   "is_system_auditor": false,
   "ldap_dn": "",
   "last_login": null,
   "external_account": null,
   "auth": []
   }

Здесь:

id – идентификатор созданного пользователя;
type – тип пользователя;
url – идентификатор ресурса;
related – связанные ссылки на другие ресурсы, такие как команды, организации, проекты, роли и другие;
summaryfields – сводные поля с информацией о возможностях пользователя, в данном случае: редактирование, удаление;
created – дата и время создания пользователя;
modified – дата и время последней модификации пользователя;
username – название учетной записи пользователя;
firstname – имя пользователя;
lastname – фамилия пользователя;
email – электронная почта пользователя;
issuperuser – сведения о том, является ли пользователь системным администратором;
issystemauditor – сведения о том, является ли пользователь системным аудитором;
ldapdn – уникальное имя пользователя в системе LDAP;
lastlogin – дата последнего входа пользователя;
externalaccount – внешний аккаунт;
auth – данные аутентификации пользователя.