Ctrl+K
Ctrl+K
Ctrl+K

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

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

В этом документе рассматривается синтаксис запросов к 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 – данные аутентификации пользователя.

Содержание