#5. REST API - Richardson API 4단계 성숙도, 좋은 REST API 특징

1. API

웹 애플리케이션에서 클라이언트와 서버는 프로토콜이라는 방법을 통해 요청과 응답을 하며 작동한다.

위와 같이 다양한 프로토콜이 있는 만큼 각 프로토콜마다 정확한 규정이 있고 이 규정이 지켜져야 컴퓨터가 정상 수행한다.

프로토콜의 사용 규정에 맞는 가이드라인이 API (Application Programming Interface) 이다.

 

2.  API - CRUD 메소드

요청, 상황	적절한 메소드
CREATE (생성)	POST
READ (조회)	GET
UPDATE (수정)	PUT (모든 정보 변경) / PATCH (일부만 변경)
DELETE (삭제)	DELETE

 

3. REST API

API는 웹에서 사용되는 Data나 resource를 HTTP URI로 표현하고, 해당 resource를 고유의 URI 로 접근하는 방식.

REST API는 REST 방식을 통해 resource에 접근하는 서비스API를 뜻한다.

HTTP 프로토콜을 기반으로 요청, 응답을 정의하는 방식.

 

4. <좋은 REST API를 디자인 하는 방식>

 

A. [0단계]

0단계 에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

[요청 메시지] 

메소드이름    /   리소스명     HTTP 버전     { JSON }

[응답 메시지]

HTTP_버전    상태코드    상태코드_메시지

 

 

B. [1단계]

개별 리소스와의 통신을 준수해야 한다.

(1)개별 리소스에 맞는 엔드 포인트를 사용.

(2)요청하고 받은 자원에 대한 정보 응답.

-예약 가능 시간 확인-

[요청 메세지] 

'허준'이라는 의사의 시간을 요청하므로, 엔드포인트에 /doctor/허준 사용. (1) 

메소드이름    /   리소스위치(doctor/허준)    / HTTP 버전 { JSON }

[응답 메세지]

요청받은 내용에 대한 응답 성공 유무 표기,  '허준'이라는 의사의 가능한 시간대별로 id를 부여해서 응답. (2)

HTTP 버전    상태코드    상태코드설명

 

-특정 시간에 예약-

[요청 메세지]

응답으로 받은 slots 의 시간대별 id를 엔드포인트에 사용하여 요청. /slots/123 (1)

메소드이름    / 리소스위치(slots/123)    /   HTTP 버전 { JSON }

[응답 메세지]

요청으로 받은 예약에 대한 성공 유무 표기, 요청으로 받은 slots/123 에 맞게 appointment 라는 신규 리소스를 명시 (2)

HTTP버전    상태코드   상태코드설명    { JSON }

 

C. [2단계]

(1). 요청의 경우, 요청 종류에 따라 CRUD에 맞는 HTTP 메소드를 사용하는 것.

0 - 1 단계에서는 모든 요청을 CRUD와 무관하게 POST로 하고 있다.

예제와 같이 시간확인은 READ의 경우 GET 메소드, 예약 생성은 CREATE의 경우 POST 이다.

(2). 응답의 경우 요청에 따른 새로운 리소스에 대해 명확한 응답 코드 작성,

클라이언트가 요청에 맞게 생성된 리소스 appointment를 Location 헤더의 URI를 통해 확인할 수 있게 한다.

-예약 가능 시간 확인-

[요청 메세지] 

'허준'이라는 의사의 가능한 시간을 확인 요청하므로, 엔드포인트에 GET/doctor/허준 사용. (1) 

메소드이름 GET    /   리소스위치(doctor/허준)    / HTTP 버전 { JSON }

[응답 메세지]

요청받은 내용에 대한 응답 성공 유무 표기,  '허준'이라는 의사의 가능한 시간을 slots의 id로 구분하여 응답. (2)

HTTP 버전    상태코드    상태코드설명  { slots : id : ~

 

-특정 시간에 예약-

[요청 메세지]

응답으로 받은 slots 의 시간대별 id를 엔드포인트에 사용하여 예약 생성 요청 POST/slots/123 (1)

메소드이름 POST   / 리소스(slots/123)    /   HTTP 버전 { JSON }

[응답 메세지]

요청으로 받은 예약 생성의 성공 유무 표기, 새로 생성된 리소스(appointment)를 Locantion 헤더에 URI로 전달 (2) 

HTTP버전    상태코드   상태코드설명  헤더 : 리소스 위치 uri 첨부  { JSON }

 

[메소드 사용의 규칙]

GET 메소드 : 서버의 데이터를 변화시키지 않는 내용에 사용. // 단순 조회

POST 메소드 : 요청마다 새로운 리소스를 생성. // 멱등성을 가지지 않는 메소드

PUT 메소드 : 요청마다 같은 리소스를 반환. // 멱등성을 가지는 메소드.

 

D. [3단계]

(1) 요청의 단계 : 2단계와 동일하게 요청의 종류에 따라 CRUD 메소드 활용.

(2) 응답의 단계 : 리소스의 URI를 포함하여 새로운 기능이 가능한 링크 요소를 삽입.

링크가 포함된 응답을 받은 다음 할 수 있는 다양한 액션들을 위해 하이퍼미디어 컨트롤을 포함.

-예약 가능 시간 확인-

[요청 메세지] 

'허준'이라는 의사의 가능한 시간을 확인 요청하므로, 엔드포인트에 GET/doctor/허준 사용. (1) 

메소드이름 GET    /   리소스위치(doctor/허준)    / HTTP 버전 { JSON }

[응답 메세지]

요청받은 내용에 대한 응답 성공 유무 표기,  '허준'이라는 의사의 가능한 시간을 slots의 id로 구분,

slots/id 별로 추가적인 액션을 진행 할 수 있도록 새로운 리소스 appointment의 URI LINK 첨부 (2)

HTTP 버전    상태코드    상태코드설명  { slots : id : ~   id별로 appointment를 생성할 URI LINK 첨부.

 

-특정 시간에 예약-

[요청 메세지]

응답으로 받은 slots 의 시간대별 id를 엔드포인트에 사용하여 예약 생성 요청 POST/slots/123 (1)

메소드이름 POST   / 리소스(slots/123)    /   HTTP 버전 { JSON }

[응답 메세지]

요청으로 받은 id에 맞는 예약 생성의 성공 유무, 요청에 의해 생성된 리소스(appointment)를 Locantion 헤더 : URI 표기, appointment 의 상세 정보를 표기하고, 추가 액션을 할 수 있는 LINK 첨부 (액션에 맞는 메소드 포함)  (2)

HTTP버전    상태코드   상태코드설명  헤더 : 리소스 위치 uri 첨부  생성된_리소스_정보표기    추가액션 URI LINK 첨부

 

 

< 좋은 REST API 특징 >

1. 리소스 중심의 올바른 엔드포인트 작성. (doctor/허준)

2. 요청에 맞는 명확한 응답 코드, 요청에 맞춘 신규 리소스에 대한 정보 기재. (appointment, 추가 액션Link)

3. CRUD에 적합한 HTTP 메소드의 사용. (GET/POST/DELETE/PUT/PATCH)