Общий формат запросов

Общий вид запросов к Yandex Tracker API:

<метод> /v2/<resources>/<resource_id>/?<param>=<value>
Host: https://api.tracker.yandex.net
Authorization: OAuth <токен>
X-Org-ID: <идентификатор организации>
{
   Тело запроса в формате JSON
} 

Методы

Запросы к Tracker API используют один из HTTP-методов:

GET — получить информацию об объекте или списке объектов;

POST — создать объект;

PATCH — изменить параметры существующего объекта. Запросы, выполненные с помощью метода PATCH изменяют только те параметры, которые явно указаны в теле запроса;

DELETE — удалить объект.

Заголовки

В запросах к Tracker API указывайте заголовки:

• Host: https://api.tracker.yandex.net

• Authorization: OAuth <ваш OAuth-токен> — при доступе по протоколу OAuth 2.0.

  Authorization: Bearer <ваш IAM-TOKEN> — при доступе по IAM-токену.

• X-Org-ID: <идентификатор организации>

  Чтобы узнать идентификатор организации, перейдите на страницу настроек Tracker. Идентификатор указан в поле ID организации для API.

Формат тела запроса

В теле запроса передается JSON-объект с идентификаторами изменяемых полей задачи и их значениями.

• Чтобы добавить или удалить значение из массива, используйте команды add и remove:

  •     {
            "followers": { "add": ["<id сотрудника1>", "<id сотрудника2>"] }
        }
    

  Команда add добавляет новые значения в массив. Чтобы перезаписать массив (удалить старые значения и добавить новые), используйте команду set.

• Чтобы обнулить значение поля, укажите значение null. Чтобы обнулить массив, используйте пустой массив []. Отдельные значения в массиве можно изменить с помощью команд target и replacement:

  • {"followers": null}

  •   {
        "followers": {
          "replace": [
              {"target": "<идентификатор1>", "replacement": "<идентификатор2>"},
              {"target": "<идентификатор3>", "replacement": "<идентификатор4>"}]
        }
      }
    

• Например, чтобы изменить тип задачи на Ошибка, используйте один из способов:

  • {"type": 1}
  • {"type": "bug"}

  •   {
          "type": { "id": "1" }
      }
    

  •   {
          "type": { "name": "Ошибка" }
      }
    

  •   {
          "type": {"set": "bug"}
      }
    

Формат текста и переменные

При работе с запросами на создание или редактирование комментариев, макросов, триггеров и автодействий используйте специальный формат для оформления текста сообщения:

• Чтобы отформатировать текст, используйте разметку Yandex Flavored Markdown.
• Чтобы добавить перенос строки, используйте символ \n.
• Чтобы добавить значения из полей задачи, используйте переменные.

Постраничное отображение результатов

Если вы запрашиваете список объектов, и количество строк в ответе больше 50, в ответе возвращается страница с указанным количеством результатов. Вы можете выполнить несколько запросов для просмотра последующих страниц. Для этого используется механизм постраничного отображения результатов.

При постраничном отображении результаты запроса рассчитываются каждый раз при отображении новой страницы. Таким образом, если за время просмотра одной страницы в результатах запроса произошли изменения, это может повлиять на отображение следующих страниц. Например, по запросу найдено 11 задач, из которых отображено 10. В процессе просмотра результатов первой страницы одна из задач была изменена и перестала отвечать требованиям поискового запроса. В этом случае, при запросе второй страницы результатов будет возвращен пустой массив, так как оставшиеся 10 задач будут находиться на первой странице.

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

• perPage (необязательный)

  Количество объектов (задач, очередей и пр.) на странице. Значение по умолчанию — 50.

• page (необязательный)

  Номер страницы ответа. Значение по умолчанию — 1.

В ответе будут содержаться следующие заголовки:

• X-Total-Pages

  Общее количество страниц с записями.

• X-Total-Count

  Общее число записей в ответе.

Примеры запросов

PATCH /v2/issues/TEST-1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>

{
  "summary": "Новое название задачи",
  "description": "Новое описание задачи",
  "type": {
      "id": "1",
      "key": "bug"
      },
  "priority": {
      "id": "2",
      "key": "minor"
      }
}

GET /v2/issues/JUNE-3?expand=attachments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>

POST /v2/issues/ HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>

{
  "queue": "TREK",
  "summary": "Test Issue",
  "parent":"JUNE-2",
  "type": "bug",
  "assignee": "<user_login>",
  "attachmentIds": [55, 56]
}

POST /v2/issues/_search?perPage=15
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>

{
  "filter": {
    "queue": "TREK",
    "assignee": "<user_login>"
  }
}