RESTful 서비스 설계와 개발 - REST 소개와 기본 구성

1. REST 소개 

• 분산 하이퍼미디어 시스템을 위하 소프트웨어 아키텍쳐
• REST(Representational safe transfer)
• Http 프로토콜의 장점을 최대한 활용할 수 있는 네트워크 기반의 아키텍쳐 

인터넷상에 REST와 관련해서 워낙 많은 정보들이 있기 때문에 자세한 내용은 생략하겠습니다. 

2.REST 기본 구성

REST는 기본적 구성  

리소스 + 메소드 + 메시지

리소스는 모든 종류의 개체, 데이터 또는 서비스이며 메소드는 행위를 의미합니다. 메시지는 요청에 대한 결과로 상태와 코드, 메시지로 구성이 되어 있습니다.  

리소스

REST API는 URI(Uniform Resource Idendifiter)를 중심으로 디자인되며 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함됩니다. 

URI 설계 규칙

• 소문자 사용. 
• 하이픈(-, hyphen) 사용 : space 대신 하이픈 사용, 일관성을 위해 under score 사용 안 함.
• 확장자 사용 안함. 
• URI 경로를 통해 리소스의 계층 관계를 표현한다. 
• URI 마지막 문자로 "/"를 포함하지 않는다. 

URI 경로 디자인

• 복수건 조회 시 복수 명사를 사용해야 한다. 
• 단건 조회 시 단수 명사를 사용해야 한다. 
• CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.
  http://www.example.com/customers/create(X)
  http://www.example.com/customers/updateCustomers(X)

REST 서비스를 설계할 때 가장 많은 시행착오를 겪은 부분입니다.

해당 리소스(데이터, 개체, 서비스)에 대한 구조와 관계를 명확히 아는 사람이 URI를 설계해야 시행착오를 줄일 수 있습니다.  

기본 원칙 

"URI를 보고 어떤 서비스에 무슨 처리를 할려는지 알 수 있어야 한다." 

예제 

Get

GET http://www.example.com/customers

모든 고객 조회

GET http://www.example.com/customers/12345

고객 ID가 12345인 고객 조회(한건)

GET http://www.example.com/customers/12345/orders

고객 ID가 12345인 고객의 모든 주문 조회 

GET http://www.example.com/customers/12345/orders/20190131001

고객 ID가 12345인 고객의 주문 중 주문 ID가 '20190131001'인 주문 조회 

Post 

POST http://www.example.com/customers

고객정보 추가   

POST http://www.example.com/customers/12345/orders

고객 ID가 12345인 고객의 주문 생성

Put

PUT http://www.example.com/customers/12345

고객 ID가 12345인 고객의 정보 수정 

PUT http://www.example.com/customers/12345/orders/98765

고객 ID가 12345인 고객의 주문 중 주문ID가 '98765'인 정보 수정 

Delete

DELETE http://www.example.com/customers/12345

고객 ID가 12345인 고객의 정보 삭제

DELETE http://www.example.com/customers/12345/orders

고객 ID가 12345인 고객의 모든 주문 정보 삭제

메소드

CRUD를 Http method를 통해 표현한다.(GET, POST, PUT, DELETE 등)

HTTP Verb	CRUD	Entire Collection (e.g. /customers)	Specific Item (e.g. /customers/{id})
POST	Create	201 (Created), 'Location' header with link to /customers/{id} containing new ID.	404 (Not Found), 409 (Conflict) if resource already exists..
GET	Read	200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.	200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT	Update/ Replace	405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH	Update/ Modify	405 (Method Not Allowed), unless you want to modify the collection itself.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE	Delete	405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable.	200 (OK). 404 (Not Found), if ID not found or invalid.

규칙

• GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안 된다. 
• GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다. 
• 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다. 
• PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다. 
• PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.
• POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다.
• POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다.
• DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다.
• OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 한다.
• 프로젝트 규칙 생성 : 생성과 수정을 동시에 처리하는 경우(SAVE) POST를 사용한다. 

메시지 

요청한 리소스의 상태와 코드, 결과 데이터들을 Json 형태로 반환한다. 

응답상태코드 (rfc2616 참고)

성공

200 : OK, 요청 정상 처리 

201 : Created, 생성 요청 성공

202 : Accepted, 비동기 요청 성공

204 : No Content, 요청 정상 처리, 응답 데이터 없음. 

실패

400 : Bad Request, 요청이 부적절 할 때, 유효성 검증 실패, 필수 값 누락 등. 

401 : Unauthorized, 인증 실패, 로그인하지 않은 사용자 또는 권한 없는 사용자 처리

403 : Forbidden, 인증 성공 그러나 자원에 대한 권한 없음. 삭제, 수정시 권한 없음. 

404 : Not Found, 요청한 URI에 대한 리소스 없을 때 사용. 

405 : Method Not Allowed, 사용 불가능한 Method를 이용한 경우. 

406 : Not Acceptable, 요청된 리소스의 미디어 타입을 제공하지 못할 때 사용.

409 : Conflict, 리소스 상태에 위반되는 행위 시 사용.

500 : 서버 에러 

REST의 소개와 기본 구성에 대해 간단히, 꼭 필요한 부분만 정리를 했습니다. 

이를 기반으로 Exception과 결과 메시지를 설계해야 합니다.  

참고 및 출처

MICROSOFT AZURE - API 디자인 

https://docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

REST API Tutorial

https://www.restapitutorial.com/lessons/httpmethods.html