Restfull 웹 API 디자인(1)

잘 디자인 된 웹 API 라면

1. 플랫폼 독립성 : 내부에서 어떤 방식으로 구현되는지와 관계없이 API를 호출할 수 있어야 한다. 표준 프로토콜을 사용

2. 서비스 진화 : API가 수정되어도(진화) 기존의 어플리케이션은 수정 없이 계속 작동할 수 있어야 한다.

 

기본 디자인 원칙

1. 리소스 중심 디자인, 클라이언트에서 접근할 수 있는 모든 종류의 개체, 데이터, 서비스가 리소스에 포함된다.

https://tacit.com/orders

2. 리소스마다 해당 리소스를 고유하게 식별하는 URI인 식별자가 있다.

https://tecit.com/orders/5

3. HTTP 요청은 독립적, 상태를 저장하지 않는다.

4. 표준 HTTP 동사 수행 : GET, POST, PUT, PATCH

5. 리소스 URI는 명사를 기반으로 해야한다

https://tecit.com/orders  // Good
https://tecit.com/add-order  // Bad

6. 여러 관계 수준을 탐색하기 위한 URI 제공시 -> 컬랙션/항목/컬렉션 보다 더 복잡하게 설계하지 않는 것이 좋다

https://tecit.com/customers/1/orders/99/products  // Bad

// Good : 2가지로 나누어서 제공
https://tecit.com/customers/1/orders
https://tecit.com/orders/99/products

7. API 요청이 많을 수록 웹서버의 부하를 높인다

8. Web API와 기본데이터 원본 사이에 종속성이 발생하지 않도록 해야한다. -> 관계형 데이터베이스 구조를 그대로 Web API 리소스로 사용할 필요가 없다.

예를 들어, premium_order, basic_order 이렇게 2가지 오더 테이블이 존재한다고 해서 /premium-orders, /basic-orders 와 같이 따라갈 필요가 없다. /orders처럼 관계형 데이터베이스를 추상화 한다.

9. 일부 작업을 특정 리소스에 매핑하지 못하는 경우 -> 의사 리소스로 표시하고 쿼리 문자열을 사용하여 필요한 매개 변수를 지정하는 URI를 제공한다

/add?operand1=99&operand2=1

 

HTTP 메서드 별 작업 정의

- GET : 리소스의 표현 검색, 응답메시지 : 리소스의 세부 정보

- POST : 새로운 리소스 생성, 요청메시지 : 새 리소스의 세부 정보

- PUT : 리소스를 만들거나 대체, 요청메시지 : 만들거나 업데이트할 리소스 지정

- PATCH : 리소스의 부분 업데이트, 요청메시지 : 리소스에 변경할 내용

- DELETE : 리소스 제거

 

 

HTTP 메서드 별 응답코드

메서드	응답코드	상태
GET	200	정상
	404	리소스를 찾을 수 없음
	204	요청이 처리 되었지만 응답 본문이 없음(콘텐츠 없음)
POST	201	새 리소스를 만드는 경우(만들어짐)
	200	일부 처리를 수행하지만 새 리소스를 만들지 않는 경우
	204	요청이 처리 되었지만 응답 본문이 없음(콘텐츠 없음)
	400	클라이언트가 잘못된 데이터를 요청에 배치한 경우 (잘못된 요청)
PUT	201	새 리소스를 만드는 경우(만들어짐)
	200 / 204	기존 리소스를 업데이트 할 경우(정상/내용없음)
	409	기존 리소스를 업데이트 할 수 없는 경우
PATCH

 

비동기작업

POST, PATCH, PUT, DELETE와 같은 작업은 시간이 오래 걸리는 경우가 있다.

처리 작업이 완료될 때 까지 기다렸다가 클라이언트에게 응답을 보내는 경우, 클라이언트가 기다리다 지쳐 타임아웃을 낼 수가 있다.

이를 방지하기 위해, 요청이 수락되었지만 아직 완료되지 않았음을 나타내는 202(수락됨) 코드가 있다.

202 코드와 함께 location 헤더에 폴링할 엔드포인트 URI를 포함하여 응답한다.

HTTP/1.1 202 Accepted
Location: /api/status/12345

 

페이지네이션

쿼리 문자열로 개수를 서버쪽에서 필터링하여 응답한다.

https://tacit.com/orders?limit=25&offset=50