기본 작성, 읽기, 업데이트, 삭제 조작은 공통 REST API 규칙에 따라 제공됩니다. 요소 유형의 최상위 레벨 URL은 해당 유형의 항목 콜렉션을 나타냅니다. 해당 유형의 모든 요소 목록을 JSON 오브젝트 배열로 렌더링하려면 HTTP 메소드 GET을 적절한 HTTP 헤더나 json 조회 매개변수와 함께 사용하십시오. 새 요소를 작성하려면 HTTP 메소드 POST를 적절한 유형의 최상위 레벨 URL에 사용하고 요청 본문에 요소의 JSON 데이터를 제공하십시오. 응답 본문에는 서버에서 생성한 id 특성과 함께 새 요소의 전체 JSON 표시가 포함됩니다. JSON 오브젝트의 배열을 제공하여 단일 요청에 여러 요소를 작성할 수도 있습니다. 이 경우, 응답 본문에 새 요소의 JSON 배열이 요청에 제공된 순서대로 포함되어 있습니다. 마찬가지로 요소의 JSON 배열이 있는 HTTP PUT 메소드를 사용하여 여러 요소의 데이터를 업데이트할 수도 있습니다. 전체 JSON 요소나 요소의 UUID만 포함된 JSON 배열이 있는 HTTP DELETE 메소드를 사용하여 여러 요소를 삭제할 수 있습니다.
기존 단일 요소에서 조작을 실행하려면 해당 요소의 UUID를 해당 유형의 최상위 레벨 URL에 추가하십시오. 예를 들어, 제공된 샘플 릴리스의 JSON 데이터에 액세스하려면 URL http://base_url/releases/00000000-0000-0000-0000-000000000036/과 함께 HTTP 메소드 GET을 사용하십시오. 요소의 데이터를 업데이트하려면 HTTP PUT 메소드를 사용하고 요청 본문에 업데이트된 JSON 오브젝트를 제공하십시오. (이 경우, 요청 URL의 UUID를 요청 본문의 id 특성보다 우선해서 사용합니다.) 요소를 삭제하려면 HTTP DELETE 메소드를 사용하십시오. 이 경우 요청 본문이 필요하지 않습니다.
작성, 읽기 및 업데이트 조작(POST, GET, PUT)을 사용하는 경우, 선택적 format 조회 매개변수를 포함하여 특정 유스 케이스에 맞게 JSON 출력을 조정할 수 있습니다. 이 매개변수를 제공하지 않거나 매개변수 값을 인식할 수 없는 경우, 기본 형식을 사용합니다. 각 요소 유형은 다른 형식 세트를 지원합니다. 이러한 형식은 요소 유형의 참조 정보와 함께 나열됩니다. 일부 형식에서는 세부사항이 길게 표시되고 일부 형식은 짧게 표시될 수 있지만 표시되는 정보만 다른 것이며 값은 같습니다.
list 및 detail 형식은 모든 요소 유형과 함께 사용할 수 있습니다. list 형식에서는 요약 정보(예: 항목 표에 표시되는 내용)를 제공합니다. detail 형식에서는 더 자세한 정보를 제공합니다. 이 형식에는 관련 요소 컨텐츠가 포함되는 경우가 많습니다. 일부 요소의 경우 이러한 형식이 동일합니다. 또한 name 특성이 있는 요소 유형은 name 형식도 있습니다. 이 형식에는 id 및 name 특성만 포함되는데 이 특성은 선택할 항목을 이름별 목록으로 표시하는 데 유용합니다. 간단하게 name을 유형의 최상위 레벨 URL에 추가해서 요소 유형의 name 형식을 생성할 수도 있습니다. 예: GET http://base_url/applications/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"}
}일부 요소 유형에서는 최상위 레벨 GET 요청에서 전체 목록 대신 요소의 서브세트를 제공할 수 있습니다. 이러한 요소 서브세트를 검색하는 경우 각 요청에서 데이터의 단일 "페이지"만 로드하기 때문에 이러한 조작을 "페이지 매기기"라고 합니다.
페이징을 대체하는 두 가지 양식이 있는데 이 양식에서는 조회 매개변수나 HTTP Range 헤더를 사용합니다.
페이지 매기기에 조회 매개변수를 사용하려면 HTTP GET 요청에 rowsPerPage 및 pageNumber 조회 매개변수를 모두 지정하십시오. 첫 번째 페이지를 검색하려면 코드 pageNumber=1을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 요청 GET http://base_url/applications/?rowsPerPage=5&pageNumber=1을 사용하십시오.
Range: items=0-4Content-Range: 0-4/10Content-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=ascfilterFields=dateCreated&filterFields=name