REST API 使用慣例

IBM® UrbanCode Release REST API 遵循一組使用慣例,以讓與它的互動變得更一致。

REST URL

伺服器上的每一個元素類型都使用複數形式代表為最上層 URL。在大多數情況下,該 URL 使用與 UCR 使用者介面中相同的術語,並使用駝峰式命名法使用慣例進行格式化。例如,變更類型是在 URL http://base_url/changeTypes/ 處予以代表,環境預約位於 URL http://base_url/environmentReservations/ 處,應用程式位於 URL http://base_url/applications/ 處,其中 base_url 是伺服器的主機名稱和路徑。

必要的 HTTP 標頭

REST API 中的大部分作業都接受採用 JSON 格式的輸入及/或傳回採用 JSON 格式的輸出。透過遵循 HTTP 使用慣例,用於提供 JSON 輸入的作業需要 Content-Type 要求標頭,用於產生 JSON 輸出的作業需要 Accept 要求標頭,以及媒體類型值 application/json。為了方便開發人員,如果媒體類型是 text/html 並且已將具有任何值的查詢參數 json 附加至要求 URL,則清單及個別項目(在下面進行說明)的 GET 方法也會產生 JSON 輸出。在沒有特殊工具來修改 Accept 標頭的情況下,此參數對於從 Web 瀏覽器呈現 JSON 輸出很有用。例如,如果要顯示所有應用程式的 JSON 輸出,請在 Web 瀏覽器的位置列中鍵入 http://base_url/applications/?json

id 內容

元素(例如,應用程式)具有唯一 ID (UUID) 內容,該內容以 JSON 字串形式作為 id 內容出現在 JSON 物件表示法中。您可以依特定元素的 UUID 來參照該元素。 您可以在諸如 REST API 作業的 URL 以及元素的 JSON 表示法內使用此 UUID。

基本作業

根據一般 REST API 使用慣例,提供了基本的建立、讀取、更新和刪除作業。某種元素類型的最上層 URL 代表該類型的項目集合。如果要將該類型之所有元素的清單作為 JSON 物件的陣列進行呈現,請將 HTTP 方法 GET 與適當 HTTP 標頭搭配使用或使用 json 查詢參數。 如果要建立新元素,請對適當類型的最上層 URL 使用 HTTP 方法 POST,並在要求內文中提供元素的 JSON 資料。回應內文包括新元素的完整 JSON 表示法,其中包含伺服器產生的 id 內容。 您還可以提供 JSON 物件的陣列,以在單一要求中建立多個元素。在此情況下,回應內文包含新元素的 JSON 陣列,這些元素的順序與在要求中提供這些元素的順序相同。同樣地,您可以透過將 HTTP PUT 方法與元素之 JSON 陣列搭配使用,來更新多個元素的資料。 您可以透過將 HTTP DELETE 方法與 JSON 陣列搭配使用來刪除多個元素,該 JSON 陣列包含完整的 JSON 元素或只包含元素的 UUID。

如果要對單個現有元素執行作業,請將該元素的 UUID 附加至該類型的最上層 URL。例如,如果要存取所提供之版本範例的 JSON 資料,請將 HTTP 方法 GET 與 URL http://base_url/releases/00000000-0000-0000-0000-000000000036/ 搭配使用。 如果要更新元素的資料,請使用 HTTP PUT 方法,並在要求內文中提供更新後的 JSON 物件。(在此情況下,要求 URL 中的 UUID 優先於要求內文中的 id 內容。)如果要刪除元素,請使用 HTTP DELETE 方法;在這種情況下,不需要任何要求內文。

輸出格式

使用建立、讀取和更新作業(POST、GET 及 PUT)時,您可以包括選用的 format 查詢參數,以針對特定的使用案例來調整 JSON 輸出。如果不提供此參數,或者該參數值無法辨識,則將使用預設格式。每一種元素類型都支援不同的格式集;這些格式列有該元素類型的參考資訊。部分格式顯示大量的詳細資訊,其他格式則顯示少量的詳細資訊,但唯一的差異是所顯示的資訊,而值均相同。

您可以將 listdetail 格式與任何元素類型搭配使用。list 格式提供摘要資訊,例如可能在項目表中顯示的資訊。 detail 格式提供較詳細的資訊。 這種格式通常包括相關元素的內容。對於部分元素,這些格式是相同的。此外,具有 name 內容的元素類型也具有 name 格式。這種格式僅包括 idname 內容,這兩個內容對於顯示項目的清單以按名稱進行選取很有用。為了方便,還可以透過將 name 附加至類型的最上層 URL(例如,GET http://base_url/applications/name)來生成元素類型的 name 格式。

JSON 輸入使用慣例

當您提供 JSON 資料作為建立或更新作業的輸入時,REST API 只考量元素上可寫入的內容。 該 API 會忽略所有其他資料。不更新唯讀內容(例如,計算的數量或建立日期)。該 API 會忽略無法辨識的內容。也不更新相關元素的內容(用於建立參照的 id 內容除外)。

例如,假定您提供下列 JSON 輸入來建立版本:
{
  "name": "New Release",
  "team": { 
    "id": "00000000-0000-0000-0000-000000000206", 
    "name": "Not the actual Team name" },
  "lifecycleModel": "00000000-0000-0000-0000-000000000006",
  "totalChanges": 42,
  "BadProperty": "xxxx"
}
當 API 處理此輸入時,該 API 只辨識建立版本期間所需的內容。因此,該 API 會忽略無法辨識的內容 BadProperty 及計算的值 totalChanges。在此情況下,上述輸入相當於下面較簡單的輸入:
{
  "name": "New Release",
  "team": "00000000-0000-0000-0000-000000000206",
  "lifecycleModel": "00000000-0000-0000-0000-000000000006"
}

同樣地,當您更新現有元素時,該 API 只變更您在 JSON 輸入中指定的內容。 該 API 不變更您省略的內容。如果要清除某個內容的值,請為該內容指定明確的 JSON 空值。

例如,考量具有下列內容的現有變更:
{
  "id": "00000000-0000-0000-0000-123456789000",
  "name": "New Feature",
  "description": "",
  "status": "In Progress",
  "type": {
    "id":"00000000-0000-1201-0000-000000000001", 
    "name":"Feature", 
    "icon":"feature"}
}
下列輸入會將變更與版本範例建立關聯,但不會更新該變更的任何其他內容。
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": "00000000-0000-0000-0000-000000000036"
}
如果要撤銷這項作業並清除此變更與版本範例的關聯,您可以使用下列輸入:
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": null
}

參照

在大多數情況下,您可以參照具有 JSON 字串(包含元素的 UUID)或 JSON 物件(包含具有相同值的 id 內容)的單一元素。如上所述,將忽略所參照元素的任何其他內容。例如,將變更與版本建立關聯時,所有下列 JSON 物件都是對等的。
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": "00000000-0000-0000-0000-000000000036"
}
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {"id":"00000000-0000-0000-0000-000000000036"}
}
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Sample Release"}
}
{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Not the actual Release name"}
}

多值(集合)參照

部分關係可以具有多個值。例如,單一版本可以與多個應用程式建立關聯。在某些情況下,當您建立或更新關係的單值端時,不會更新這些關係。例如,當您建立版本時,您為 applications 內容提供的值沒有效果。請改為使用其他 URL 從版本中新增或移除應用程式:
  • 列出與某個版本相關的應用程式:GET /releases/{releaseID}/applications
  • 將應用程式新增至版本:POST /releases/{releaseID}/applications/{applicationID}
  • 從版本中移除應用程式:DELETE /releases/{releaseID}/applications/{applicationID}

不過,在其他情況下,特別是當某個元素需要特定的關係時,您可以為關係的單值端指定輸入。例如,可以將某個應用程式與多個小組建立關聯。在此情況下,當您建立應用程式時,您可以為 "teams" 內容提供 UUID 字串的 JSON 陣列。 沒有特殊 URL 用來處理這種關係。

鍵值內容

部分元素類型支援儲存和擷取開放式鍵值組以及靜態定義的內容。這種類型的內容通常代表已鏈結至某個整合提供者的資料。例如,代表 IBM Rational® Team Concert 工作項目的變更可能會將該工作項目的 ID 儲存為此鍵值儲存體中的某個內容。

鍵值內容在 JSON 資料中代表為 properties 內容下面的一個相關元素。 例如,下列程式碼代表具有名為 firstsecondthird 之鍵值內容的變更:
{
  "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 要求可以提供元素的子集,而不是完整清單。像這樣來擷取元素的子集一般稱為「分頁」,因為它涉及到只載入每個要求中單一「頁面」的資料。

提供了兩種替代形式的分頁:使用查詢參數或 HTTP Range 標頭。

如果要使用查詢參數進行分頁,請在 HTTP GET 要求中同時指定 rowsPerPagepageNumber 查詢參數。如果要擷取首頁,請指定程式碼 pageNumber=1。 例如,如果要擷取前 5 個應用程式,請使用要求 GET http://base_url/applications/?rowsPerPage=5&pageNumber=1

如果要使用 HTTP Range 標頭,請指定項目範圍的起始值和終止值,並指定從 0 開始的值和包含值。例如,如果要擷取前 5 個應用程式,請將下列標頭新增至要求 GET http://base_url/applications/
Range: items=0-4
不論您如何要求分頁,HTTP 回應都使用 Content-Range 標頭來指定所擷取的實際範圍及可用項目的總數。例如,如果您要求了某個清單(包含 10 項)的前 5 個變更,則回應包括下列標頭:
Content-Range: 0-4/10
如果您要求了前 5 個變更,但卻只有 3 個變更可用,則該標頭如下所示:
Content-Range: 0-2/3

排序

如果要將最上層 GET 作業的結果進行排序,請指定 orderFieldsortType 參數。 orderField 參數必須包含作為排序依據之單一內容的名稱。sortType 參數必須包含值 asc(用來以遞增順序進行排序)或值 desc(用來以遞減順序進行排序)。

如果要將相關元素的內容進行排序,請指定帶點路徑格式的內容名稱。例如,如果要根據相關聯的版本對變更清單進行排序,請指定值 release.name。 如果此路徑中的任何內容都是空值,則表示未指定排序。

您可以將排序與分頁及 format 參數相結合。 例如,如果要以 detail 格式擷取前 5 個變更(按相關版本的名稱依遞增順序進行排序),請使用下列要求:
GET http://base_url/changes/?format=detail&rowsPerPage=5&
  pageNumber=1&orderField=release.name&sortType=asc 
並非所有內容都可以用於進行排序。尤其是,用於代表摘要資料的內容(例如,項目數)通常無法用於進行排序。

過濾

如果要過濾結果,請指定查詢參數。部分查詢參數的名稱基於您用於過濾結果之資料內容的名稱。 例如,下列要求顯示在指定日期建立的版本:
GET http://base_url/releases/
  ?filterFields=dateCreated
  &filterType_dateCreated=gt
  &filterClass_dateCreated=Long
  &filterValue_dateCreated=1421171883574
  &orderField=dateCreated
  &sortType=asc
此範例使用下列查詢參數:
filterFields
此參數指定用於過濾結果的欄位。 在前一個範例中,代碼 filterFields=dateCreated 依特定日期過濾結果。 如果要依多個欄位進行過濾,請重複此參數,如以下範例所示:
filterFields=dateCreated&filterFields=name
filterType_propertyName
此參數指定要對指定內容執行之過濾作業的類型。前一個範例具有內容值 filterType_dateCreated=gt。 此代碼指定 dateCreated 內容的過慮作業顯示晚於指定日期的值。受支援的過慮作業包括 likeeq(等於)、ne(不等於)、gt(大於)、ge(大於或等於)、lt(小於)、le(小於或等於)、nullnotnullrangein
filterClass_propertyName
此內容指定您提供給過濾器的資料類型。在前一個範例中,日期為一個長整型 Unix 時間戳記值:filterClass_dateCreated=Long。 有效資料類型為 BooleanLongStringUUIDEnum
每一種資料類型支援特定的過濾器類型集合:
  • 字串:likeeqnegtgeltlenullnotnullrangein
  • 長:eqnegtgeltlenullnotnullrangein
  • 布林:eqnenullnotnull
  • UUID:eqnenullnotnull
  • 列舉:eqnenullnotnull
filterValue_propertyName
此參數指定用於過濾結果的值。 前一個範例指定 Unix 時間戳記格式的日期。如果是使用過濾器類型 rangein,請多次指定此參數以定義值範圍或值集。 過濾器類型 nullnotnull 不需要任何參數。

意見