Соглашения для API REST

API REST IBM® UrbanCode Build подчиняется набору соглашений, обеспечивающих согласованное взаимодействие.

URL REST

Каждый тип элементов на сервере представляется в виде URL верхнего уровня в форме множественного числа. В большинстве случаев URL использует термины из пользовательского интерфейса, отформатированные в смешанном регистре. Например, шаблоны процессов представлены с помощью URL http://базовый-url/processTemplates/, пулы агентов - с помощью URL http://базовый-url/agentPools/, а потоки операций - с помощью URL http://базовый-url/workflows/, где базовый-url - это имя хоста и путь к серверу.

Обязательные заголовки HTTP

Большинство операций API REST принимают входные данные и/или возвращают выходные данные в формате JSON. В соответствии с соглашениями HTTP заголовок запроса Content-Type требуется для операций с входными данными JSON, а заголовок запроса Accept требуется для операций с выходными данными JSON и значением типа содержимого application/json. Для удобства разработчиков метод GET для списков и отдельных элементов (см. ниже) также создает выходные данные JSON, если указан тип содержимого text/html и в URL запроса добавлен параметр json с любым значением. Этот параметр удобен для вывода выходных данных JSON из веб-браузера без специальных инструментов, изменяющих заголовок Accept. Например, для просмотра вывода JSON для всех модулей откройте в браузере следующий адрес: http://базовый-url/plugins/?json.

Свойство `id`

Элементы, такие как проекты, должны иметь свойство уникального ИД (UUID) (свойство id в представлении объекта JSON в виде строки JSON). К конкретному элементу можно обратиться с помощью UUID. Например, этот UUID можно использовать в URL операций API REST, а также в представлениях JSON элементов.

Основные операции

Базовые операции создания, чтения, обновления и удаления предоставлены в соответствии с общими соглашениями API REST. URL верхнего уровня для типа элемента представляет набор элементов этого типа. Для вывода всех элементов этого типа в качестве массива объектов JSON укажите метод GET HTTP с соответствующими заголовками HTTP или параметром запроса json. Для создания нового элемента выполните метод POST HTTP для URL верхнего уровня требуемого типа и укажите данные JSON для элемента в теле запроса. Тело ответа содержит полное представление JSON нового элемента, включая созданное сервером свойство id. Кроме того, можно указать массив объектов JSON для создания нескольких элементов в одном запросе. В этом случае тело ответа содержит массив JSON новых элементов в том порядке, в котором они указаны в запросе. Аналогичным образом, можно обновить данные для нескольких элементов с помощью метода PUT HTTP с массивом JSON элементов. Несколько элементов можно удалить с помощью метода DELETE HTTP с массивом JSON, содержащим полные элементы JSON или UUID элементов.

Для выполнения операции над отдельным существующим элементом добавьте UUID элемента в URL верхнего уровня типа. Например, для доступа к данным JSON из приведенного модуля Ant можно использовать метод GET HTTP со следующим URL: http://базовый-url/plugins/d43aa71e-5acc-4e28-8b4c-b19ee2b214be/. Данные элемента можно обновить с помощью метода PUT HTTP, указав обновленный объект JSON в теле запроса. (В этом случае UUID в URL запроса обладает более высоким приоритетом по сравнению со свойством id в теле запроса). Для удаления элемента применяется метод DELETE HTTP; в этом случае тело запроса не требуется.

Форматы вывода

В операции создания, чтения и обновления (POST, GET и PUT) можно добавить необязательный параметр запроса format, позволяющий настроить формат выходных данных JSON. Если этот параметр не указан или содержит неизвестное значение, то применяется формат по умолчанию. Каждый тип элементов поддерживает собственный набор форматов; эти форматы перечислены в справочной информации по типу элементов. Форматы предлагают разные уровни подробности, однако различие заключается только в отображаемой информации; значения совпадают.

Форматы list и detail поддерживаются всеми типами элементов. Формат list предлагает сводную информацию, такую как содержимое таблицы элементов. Формат detail предлагает более подробную информацию. Часто этот формат включает содержимое связанных элементов. Для отдельных элементов эти форматы совпадают. Кроме того, для типов элементов, содержащих свойство name, предусмотрен формат name. Этот формат включает только свойства id и name, которые упрощают отображение списка элементов для выбора по имени. Для удобства формат name для типа элементов можно создать путем добавления свойства name в URL верхнего уровня типа, например GET http://базовый-url/jobs/name.

Соглашения для входных данных JSON

В случае предоставления входных данных JSON для операций создания и обновления API REST учитывает только те свойства элемента, которые доступны для записи. API игнорирует все остальные данные. Доступные только для чтения свойства, такие как вычисляемые значения или даты создания, не обновляются. API игнорирует неизвестные свойства. Свойства связанных элементов, отличные от свойства id, применяются для создания ссылки и также не обновляются.

В качестве примера предположим, что для создания проекта применяются следующие входные данные JSON:

{
  "name": "New Project",
  "teams": "My Team",
  "totalChanges": 42,
  "tags": ["green"],
  "BadProperty": "xxxx"
}

В ходе обработки этих входных данных API распознает только свойства, необходимые для создания выпуска. Таким образом, он игнорирует свойство BadProperty и вычисляемое значение totalChanges. В этом случае входные данные эквивалентны следующим более простым входным данным:

{
  "name": "New Project",
  "teams": "My Team",
  "tags": ["green"],
}

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

Например, следующий ввод изменяет свойство tags в примере проекта, но не изменяет другие свойства:

{
  "id": "123456789000",
  "name": "New Project",
  "tags": ["green","blue"],
  }

Ссылки

В большинстве случаев к отдельному элементу можно обратиться с помощью строки JSON, содержащей UUID элемента, или с помощью объекта JSON, содержащего свойство id с тем же значением. Обратите внимание, что остальные свойства связанного элемента игнорируются. Например, следующие объекты JSON эквивалентны в случае связывания изменения с проектом.

{
  "id": "00000000-0000-0000-0000-123456789000",
  "project": "00000000-0000-0000-0000-000000000036"
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "project": {"id":"00000000-0000-0000-0000-000000000036"}
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "project": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Sample Project"}
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "project": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Not the actual Project name"}
}

Ссылки с несколькими значениями (набор)

Отдельные отношения имеют несколько значений. Например, один проект можно связать с несколькими процессами. В отдельных случаях такие отношения не обновляются при создании или обновлении значения с одной стороны отношения. Например, при создании проекта игнорируются значения, указанные для свойства buildprocesses. Для добавления или удаления процессов компоновки из проектов следует использовать другие URL.

Свойства ключ-значение

Отдельные типы элементов поддерживают сохранение и извлечение пар ключ-значение в дополнение к статическим свойствам. Свойства такого типа представляют данные, связанные таким же образом.

Свойства ключ-значение представлены в данных JSON в качестве связанного элемента в свойстве properties. Например, следующий код представляет изменение со свойствами ключ-значение с именами first, second и third:

{
  "id": "00000000-0000-0000-0000-123456789000",
  "name": "New Feature",
  "description": "",
  "status": "In Progress",
  "type":{
    "id":"00000000-0000-1201-0000-000000000001", 
    "name":"Feature", 
    "icon":"feature"},
  "properties":{ 
    "first":"first value", 
    "second":"second value", 
    "third":"third value"}
}

Ключ и значение должны представлять собой строки JSON. Как и в случае статических свойств, если во входных данных не указан ключ, то операции обновления не изменяют его. Для того чтобы сбросить пару ключ-значение, присвойте ключу пустое значение JSON.

Разбиение на страницы

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

Доступно два способа разбиения на страницы: с помощью параметров запроса или заголовка Range HTTP.

Для разбиения на страницы в запросе GET HTTP можно указать параметры запроса rowsPerPage и pageNumber. Для извлечения первой страницы укажите код pageNumber=1. Например, для извлечения первых пяти приложений, выполните запрос GET http://базовый-url/jobs/?rowsPerPage=5&pageNumber=1.

Для применения заголовка Range HTTP укажите начальное и конечное значения для диапазона элементов (включаемые значения с отсчетом от нуля). Например, для извлечения первых пяти заданий добавьте следующий заголовок в запрос GET http://базовый-url/jobs/:

Range: items=0-4

Вне зависимости от способа запроса разбиения на страницы ответ HTTP содержит заголовок Content-Range с фактическим диапазоном и общим числом доступных элементов. Например, если запрошены первые пять заданий из списка, содержащего десять записей, то ответ будет содержать следующий заголовок:

Content-Range: 0-4/10

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

Content-Range: 0-2/3

Сортировка

Для сортировки результатов операции GET верхнего уровня укажите параметры orderField и sortType. Параметр orderField должен содержать имя отдельного свойства для сортировки. Параметр sortType должен содержать значение asc для сортировки по возрастанию или значение desc для сортировки по убыванию.

Комментарии