[ 一日30分 인생승리의 학습법 ] REST API 규칙

 

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 규칙에 따라 매체 유형 값 application/json을 사용하며 JSON 입력을 제공하는 조작에는 Content-Type 요청 헤더가 필요하고 JSON 출력을 생성하는 조작에는 Accept 요청 헤더가 필요합니다. 개발자의 편의를 위해서 매체 유형이 text/html이고 조회 매개변수 json이 임의의 값으로 요청 URL에 추가된 경우, 목록 및 개별 항목(아래에 표시됨)의 GET 메소드에서도 JSON 출력을 생성합니다. 이 매개변수는 Accept 헤더를 수정하는 특수 도구 없이 웹 브라우저에서 JSON 출력을 렌더링하는 데 유용합니다. 예를 들어, 모든 애플리케이션에 대한 JSON 출력을 표시하려면 웹 브라우저의 위치 표시줄에 http://base_url/applications/?json을 입력합니다.

id 특성

애플리케이션과 같은 요소에는 고유 ID(UUID) 특성이 있으며 이 특성은 JSON 오브젝트 표시에서 JSON 문자열과 같은 id 특성으로 표시됩니다. 해당 UUID를 사용하여 특정 요소를 참조할 수 있습니다. 이 UUID를 REST API 조작의 URL 위치나 요소의 JSON 표시 내에 사용할 수 있습니다.

기본 조작

기본 작성, 읽기, 업데이트, 삭제 조작은 공통 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 입력 규칙

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에서는 이 입력을 처리할 때 릴리스 작성에 필요한 특성만 인식합니다. 따라서 인식되지 않는 특성인 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
}

참조

일반적으로 요소의 UUID가 포함된 JSON 문자열이나 같은 값이 있는 id 특성이 포함된 JSON 오브젝트를 사용하여 단일 요소를 참조할 수 있습니다. 위 설명과 같이 참조된 요소의 다른 특성은 무시됩니다. 예를 들어, 다음 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 요청에 rowsPerPage 및 pageNumber 조회 매개변수를 모두 지정하십시오. 첫 번째 페이지를 검색하려면 코드 pageNumber=1을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 요청 GET http://base_url/applications/?rowsPerPage=5&pageNumber=1을 사용하십시오.

HTTP Range 헤더를 사용하려면 항목 범위의 시작 및 종료 값을 지정하여 영(0) 기반 포함 값을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 다음 헤더를 요청 GET http://base_url/applications/에 추가하십시오.
Range: items=0-4
페이지 매기기 요청 방법에 관계 없이 HTTP 응답에서는 Content-Range 헤더를 사용하여 검색되는 실제 범위와 사용 가능한 총 항목 수를 지정합니다. 예를 들어, 열 개 목록 중에 처음 다섯 개의 변경사항을 요청하는 경우 응답에 다음 헤더가 포함됩니다.
Content-Range: 0-4/10
처음 다섯 개 변경사항을 요청하고 있지만 세 개의 변경사항만 있는 경우, 헤더가 다음과 같이 표시됩니다.
Content-Range: 0-2/3

정렬

최상위 레벨 GET 오퍼레이션의 결과를 정렬하려면 orderField 및 sortType 매개변수를 지정하십시오. orderField 매개변수에는 정렬에 사용할 단일 특성 이름이 포함되어야 합니다. sortType 매개변수에는 오름차순으로 정렬하는 값 asc 또는 내림차순으로 정렬하는 값 desc가 포함되어야 합니다.

관련 요소의 특성을 정렬하려면 특성 이름을 마침표로 구분된 경로 형식으로 지정하십시오. 예를 들어, 연관 릴리스에 따라 변경사항 목록을 정렬하려면 값 release.name을 지정하십시오. 이 경로의 특성 중 하나가 널이면 순서가 지정되지 않습니다.

정렬을 페이지 매기기 및 format 매개변수와 결합할 수 있습니다. 예를 들어 detail 형식으로 처음 다섯 개의 변경사항을 관련 릴리스 이름에 따라 오름차순으로 정렬하여 검색하려면 다음 요청을 사용하십시오.
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(이하), nullnotnullrange 및 in.
filterClass_propertyName
이 특성은 사용자가 필터에 제공하는 데이터 유형을 지정합니다. 이전 예에서 날짜는 Unix 시간소인 값인 long 정수입니다. filterClass_dateCreated=Long. 유효한 데이터 유형은 BooleanLongStringUUID 및 Enum입니다.
각 데이터 유형은 특정 필터 유형 세트를 지원합니다.
  • 문자열: likeeqnegtgeltlenullnotnullrange 및 in
  • Long: eqnegtgeltlenullnotnullrange 및 in
  • 부울: eqnenullnotnull
  • UUID: eqnenullnotnull
  • Enum: eqnenullnotnull
filterValue_propertyName
이 매개변수는 결과를 필터링하는 기준 값을 지정합니다. 이전 예에서는 Unix 시간소인 형식으로 날짜를 지정합니다. range 또는 in 필터 유형을 사용하는 경우 이 매개변수를 여러 차례 지정하여 값 세트나 범위를 정의하십시오. null 및 notnull 유형의 필터에는 매개변수가 필요하지 않습니다.

 

 

본 웹사이트는 광고를 포함하고 있습니다.
광고 클릭에서 발생하는 수익금은 모두 웹사이트 서버의 유지 및 관리, 그리고 기술 콘텐츠 향상을 위해 쓰여집니다.
번호 제목 글쓴이 날짜 조회 수
1088 [ 一日30分 인생승리의 학습법 ] Build Your Own Remote Desktop Application using Javascript, Python & WebRTC — Part 2 file 졸리운_곰 2022.08.05 5
1087 [ 一日30分 인생승리의 학습법 ] Build Your Own Remote Desktop Application using Javascript, Python & WebRTC — Part 1 file 졸리운_곰 2022.08.05 2
» [ 一日30分 인생승리의 학습법 ] REST API 규칙 졸리운_곰 2022.08.03 0
1085 [ 一日30分 인생승리의 학습법 ]REST API 설계 (네이밍) 졸리운_곰 2022.08.03 0
1084 [ 一日30分 인생승리의 학습법] [2탄!!] KrakenD Demo 면을 알아보죠! file 졸리운_곰 2022.08.01 0
1083 [ 一日30分 인생승리의 학습법] [1탄!!]KrakenD가 무엇인가? 과연 Api Gateway로 으뜸인가요? file 졸리운_곰 2022.08.01 0
1082 [ 一日30分 인생승리의 학습법] 오픈소스 라이선스 별 의무사항 졸리운_곰 2022.07.29 0
1081 [ 一日30分 인생승리의 학습법] The complete guide to (external) Domain Specific Languages file 졸리운_곰 2022.07.08 3
1080 [ 一日30分 인생승리의 학습법] [Elasticsearch] 기본 개념잡기 file 졸리운_곰 2022.06.02 7
1079 [ 一日30分 인생승리의 학습법]node - pm2로 node.js 프로세스 관리하기 - 기본 명령어, 실행하기 file 졸리운_곰 2022.05.28 3
1078 [ 一日30分 인생승리의 학습법][1탄!!]KrakenD가 무엇인가? 과연 Api Gateway로 으뜸인가요? file 졸리운_곰 2022.04.15 5
1077 [ 一日30分 인생승리의 학습법][API Gateway] Kong Gateway 설치 file 졸리운_곰 2022.04.15 3
1076 [ 一日30分 인생승리의 학습법] TeX_및_LaTeX_수식_문법 file 졸리운_곰 2022.03.19 23
1075 [ 一日30分 인생승리의 학습법] Visual Basic application on linux 졸리운_곰 2022.02.22 5
1074 [ 一日30分 인생승리의 학습법] Truffle을 이용한 DApp 개발환경 구성 file 졸리운_곰 2022.02.20 78
1073 [ 一日30分 인생승리의 학습법]LaTeX 활용해서 논문쓰장 file 졸리운_곰 2022.02.17 10
1072 [ 一日30分 인생승리의 학습법] LaTeX 초보자가 감을 잡는 것을 돕는 몇가지 팁 졸리운_곰 2022.02.17 7
1071 [ 一日30分 인생승리의 학습법] 수식 입력이 가능한 마인드맵 프로그램, 프리플레인(freeplane) file 졸리운_곰 2022.02.16 13
1070 [ 一日30分 인생승리의 학습법] Awesome Metaverse Awesome 짱!~ 메티버스 오픈소스 file 졸리운_곰 2022.02.13 4
1069 [ 一日30分 인생승리의 학습법] 제 NAS의 Docker 목록 file 졸리운_곰 2022.01.31 22
대표 김성준 주소 : 경기 용인 분당수지 U타워 등록번호 : 142-07-27414
통신판매업 신고 : 제2012-용인수지-0185호 출판업 신고 : 수지구청 제 123호 개인정보보호최고책임자 : 김성준 sjkim70@stechstar.com
대표전화 : 010-4589-2193 [fax] 02-6280-1294 COPYRIGHT(C) stechstar.com ALL RIGHTS RESERVED