Rest API 공식 문서
JSON 과 Javascript 차이
참고 깃허브
REST란?
웹을 서비스를 디자인하는 아키텍처 접근 방식, 즉 하이퍼 미디어 기반 분산 시스템을 구축하기 위한 아키텍처 스타일.
•
RestAPI는 리소스를 중심으로 디자인, 클라이언트에서 액세스 할 수 있는 모든 종류의 개체, 데이터 또는 서비스
•
리소스를 고유하게 식별하는 URI인 식별자가 있다.
// 예시: 특정 고객 주문의 URI를 표현
https://adventure-works.com/orders/1
JavaScript
복사
•
균일한 인터페이스로 클라이언트와 서비스 구현을 분리하는 데 도움이 된다.
•
REST API는 상태 비저장 요청 모델 사용.
요청은 독립적, 웹 서비스의 확장성에 유리하다.
리소스를 중심으로 API 디자인 구성
웹 API가 표시하는 비즈니스 엔티티에 집중해야된다. 가능하다면 리소스 URI는 동사가 아닌 명사를 기반으로 작업해야된다.
https://adventure-works.com/orders // Good
https://adventure-works.com/create-order // Avoid
JavaScript
복사
리소스가 실제 데이터 항목을 기반으로 할 필요는 없다. 단순히 데이터 베이스의 내부 구조를 반영하는 API는 만들면 안된다 (DB구조를 그냥 리턴하면 안된다). DTO를 적극 사용해서, 데이터 베이스의 구조가 노출이 되면 안된다.
URI에 일관적인 명명 규칙을 적용해야된다
컬렉션 및 항목에 대한 URI를 계층 구조로 구성하는 것이 좋다. 예를 들어 /customers는 컬렉션의 경로, /customers/5 는 ID가 5인 고객의 경로.
서로 다른 리소스들과 연결 관계도 고려해야된다.
/customers/5/orders 는 고객 5번의 주문을 나타낼 수 있고, /orders/99/customers 처럼 주문으로 부터 고객과의 연결을 표시할 수도 있겠지만, 이 모델을 너무 많이 확장하면 구현이 어려워 질 수 있다.
차라리 응답 메시지 본문에 연결된 리소스에 대한 링크를 제공하는 방법이 더 좋다. 좀 더 복잡한 시스템에서는 /customers/1/orders/99/products 처럼 복잡한 수준이 필요할 수 있겠으나, 이 수준의 복잡성은 엔티티의 관계가 변한다면 유지하기 어려울 수 있다. 비교적 간단하게 URI를 관리하는 것을 추천 → RESTful
리소스 URI를
컬렉션/항목/컬렉션 보다 더 복잡하게 요구하지 않는 것이 좋다.
HTTP 메소드 API 작업 정의
•
GET은 지정된 URI에서 리소스의 표현을 검색합니다. 응답 메시지의 본문은 요청된 리소스의 세부 정보를 포함하고 있습니다.
•
POST는 지정된 URI에 새 리소스를 만듭니다. 요청 메시지의 본문은 새 리소스의 세부 정보를 제공합니다. 참고로 POST를 사용하여 실제로 리소스를 만들지 않는 작업을 트리거할 수도 있습니다.
•
PUT은 지정된 URI에 리소스를 만들거나 대체합니다. 요청 메시지의 본문은 만들 또는 업데이트할 리소스를 지정합니다.
•
PATCH는 리소스의 부분 업데이트를 수행합니다. 요청 본문은 리소스에 적용할 변경 내용을 지정합니다.
•
DELETE는 지정된 URI의 리소스를 제거합니다.
POST / PUT 및 PATCH의 차이점
•
POST 요청은 리소스를 만드는 역할. 서버는 새로운 리소스에 대한 URI를 할당하고 클라이언트에 해당 URI를 반환한다. 하지만 리소스를 만들지 않고 데이터 처리를 위해서 사용하는 경우도 있다 (login 같은거)
•
PUT요청은 리소스를 만들거나, 기존 리소스를 대체하는 역할. 해당 URI를 사용하는 리소스가 이미 있으면 리소스가 대체된다. 리소스가 없고 서버가 만들기를 지원한다면 리소스가 생성이 된다. PUT 요청은 컬렉션 보다 특정 고객 같은 개별항목 리소스에 자주 적용이된다. PUT 요청은 idempotent 이어야 한다. 여러번 요청하더라도 그 결과가 항상 같아야 된다.
PUT 요청은 idempotent 이어야 한다. 여러번 요청하더라도 그 결과가 항상 같아야 된다. •
PATCH 요청은 기존리소스의 부분 업데이트를 수행한다. 클라이언트는 리소스의 URI를 지정하고, 요청 본문은 리소스에 적용할 변경 내용을 저장한다.
미디어 유형
HTTP 프로토콜에서 MIME타입이라고 한느 미디어 유형을 사용한다. 이진이 아닌 데이터의 경우 대부분의 웹 API는 JSON(application/json) 및 xml(application/xml)을 지원한다.
요청 / 응답의 헤더에서 Content-Type 헤더는 미디어 유형을 지정한다.
POST https://adventure-works.com/orders HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 57
{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}
JavaScript
복사
JSON 데이터를 포함한 POST요청의 예시
서버에서 해당 미디어 유형을 지원하지 않으면 415(지원되지 않는 미디어 유형)를 반환해야된다.
메소드 별 상태 코드
GET 메소드
성공시에는 상태코드 200[정상] 을 반환하고, 찾을 수 없는 경우 404[찾을 수 없음]을 반환해야된다. 요청이 처리가 되어도 응답 본문이 없다면 204[콘텐츠 없음]을 반환해야된다.
POST 메소드
POST 메소드는 새 리소스를 만드는 경우 201[만들어짐] 을 반환한다. 처리를 수행하고 새 리소스를 만들지 않는 경우는 200을 반환하고 작업 결과를 응답 바디에 반환할 수 있다. 반환할 결과가 없으면 204[내용없음] 을 반환할 수 있다.
PUT 메소드
PUT메소드는 POST 메소드와 마찬가지로 새 리소스가 생성이 되면 201[만들어짐] 을 반환한다. 업데이트 시에는 200[정상] 또는 204[내용없음]를 반환한다. 업데이트를 할 수 없는 경우라면 409[충돌]을 반환해야 할 수 있다.
PATCH 메소드
클라이언트는 PATCH 요청을 사용해서 업데이트를 패치 문서의 형태로 기존 리소스에 보낸다. 패치 문서는 리소스 전체가 아니라 적용할 변경 내용만 설명한다.
패치는 기존 JSON 리소스와 동일한 구조를 갖지만, 변경 또는 추가할 필드만 포함하고 있다. 또한 필드에 null값을 지정하여 해당 필드를 삭제할 수 도 있다. ( 필드가 null을 허용하면 삭제되지 않는다)
예시 :{
"name":"gizmo",
"category":"widgets",
"color":"blue",
"price":10
}
JavaScript
복사
기존 데이터가 이런 형태라고 한다면,
{
"price":12,
"color":null,
"size":"small"
}
JavaScript
복사
이런 형태로 price를 업데이트하고 color를 삭제하고 size를 추가하도록 지시할 수 있다. 여기서 name과 category는 수정되지 않는다.
PATCH 요청에서 발생할 수 있는 오류들 :
DELETE 메소드
삭제 작업이 성공하면 응답 본문에 추가 정보가 없음을 나타내는 204[컨텐츠 없음] 으로 응답해야한다. 리소스를 찾을 수없다면 404[찾을 수 없음]로 응답
비동기 작업
요청을 처리하는 데 시간이 걸리는 작업일 수가 있다. 하지만 클라이언트 입장에서는 해당 서버가 뻗은 것 같은 경험을 할 수 가 있는데, 이런 경우는 비동기 작업을 고려해야한다. 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 202[수락됨] 를 반환해야한다.