根據一般 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 輸出。如果不提供此參數,或者該參數值無法辨識,則將使用預設格式。每一種元素類型都支援不同的格式集;這些格式列有該元素類型的參考資訊。部分格式顯示大量的詳細資訊,其他格式則顯示少量的詳細資訊,但唯一的差異是所顯示的資訊,而值均相同。
您可以將 list 和 detail 格式與任何元素類型搭配使用。list 格式提供摘要資訊,例如可能在項目表中顯示的資訊。 detail 格式提供較詳細的資訊。 這種格式通常包括相關元素的內容。對於部分元素,這些格式是相同的。此外,具有 name 內容的元素類型也具有 name 格式。這種格式僅包括 id 和 name 內容,這兩個內容對於顯示項目的清單以按名稱進行選取很有用。為了方便,還可以透過將 name 附加至類型的最上層 URL(例如,GET http://base_url/applications/name)來生成元素類型的 name 格式。
當您提供 JSON 資料作為建立或更新作業的輸入時,REST API 只考量元素上可寫入的內容。 該 API 會忽略所有其他資料。不更新唯讀內容(例如,計算的數量或建立日期)。該 API 會忽略無法辨識的內容。也不更新相關元素的內容(用於建立參照的 id 內容除外)。
{
"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"
}
{
"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
}
{
"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"}
}
不過,在其他情況下,特別是當某個元素需要特定的關係時,您可以為關係的單值端指定輸入。例如,可以將某個應用程式與多個小組建立關聯。在此情況下,當您建立應用程式時,您可以為 "teams" 內容提供 UUID 字串的 JSON 陣列。 沒有特殊 URL 用來處理這種關係。
部分元素類型支援儲存和擷取開放式鍵值組以及靜態定義的內容。這種類型的內容通常代表已鏈結至某個整合提供者的資料。例如,代表 IBM Rational® Team Concert 工作項目的變更可能會將該工作項目的 ID 儲存為此鍵值儲存體中的某個內容。
{
"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 要求中同時指定 rowsPerPage 和 pageNumber 查詢參數。如果要擷取首頁,請指定程式碼 pageNumber=1。 例如,如果要擷取前 5 個應用程式,請使用要求 GET http://base_url/applications/?rowsPerPage=5&pageNumber=1。
Range: items=0-4
Content-Range: 0-4/10
如果您要求了前 5 個變更,但卻只有 3 個變更可用,則該標頭如下所示:Content-Range: 0-2/3
如果要將最上層 GET 作業的結果進行排序,請指定 orderField 和 sortType 參數。 orderField 參數必須包含作為排序依據之單一內容的名稱。sortType 參數必須包含值 asc(用來以遞增順序進行排序)或值 desc(用來以遞減順序進行排序)。
如果要將相關元素的內容進行排序,請指定帶點路徑格式的內容名稱。例如,如果要根據相關聯的版本對變更清單進行排序,請指定值 release.name。 如果此路徑中的任何內容都是空值,則表示未指定排序。
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=dateCreated&filterFields=name