REST API

REST?

REspresentational State Transfer

Resprensentation	State	Transfer
표현	상태	전이

 

REST는 문자 그대로 상태의 전이를 표현하기 위한 HTTP상의 아키텍처 스타일이다.

여기서 상태, State는 Resourse의 State를 말한다.

Resource는 파일, 문서, 데이터 등을 모두 포함하고 있으며, 이러한 데이터를 응답해주는 역할을 하고, 데이터는 도메인 모델에 대한 데이터이기 때문에 Resource자체가 Domain Model을 칭한다고 해도 무방하다.

 

Resprensentation 구성 요소

URL(Resource)

URL를 통해 Resource의 이름을 표현한다.

e.g. /models

Method(Verb)

HTTP의 Method를 통해 상태를 변경하는 행위(Verb)를 표현한다.

HTTP Methods

GET : read 요청, Resource의 정보를 획득하기 위해 사용

POST : Create 요청, 새로운 Resource를 생성하기 위해 사용.

PUT : Update 요청, Resource에 대한 정보 수정을 위해 사용. 수정되는 정보를 포함한 모든 Resource의 정보를 포함하여 요청

PATCH : Update 요청, Resource에 대한 정보 수정을 위해 사용. 수정되는 정보만 요청

DELETE : Delete 요청, Reource를 삭제하기 위해 사용.

OPTIONS : 서버와 클라이언트 사이의 통신 옵션을 확인하기 위해 사용. REST에서 표현을 위해 사용하진 않고, HTTP에서 보안 및 효율성을 위해 자동적으로 생성되는 요청

JSON, XML 등(Representation of Resource)

Resource의 상태를 표현하는 방법

어떠한 형태의 데이터 구조를 사용해도 무방하다.

 

REST style API 디자인 가이드

• URL은 명사, 소문자, 복수형을 사용하는것을 권장한다.
  • e.g. /posts
• / 를 통해 Resource간의 계층관계를 표현한다. / 는 has 를 의미한다고 보면 이해하기 쉽다.
  • e.g. /posts/{id}/comments
• URL의 마지막에 /를 포함하지 않는다.
  • e.g. /posts/ 형태 지양
• 밑줄(_)은 사용하지 않아야 하며, 가독성을 높히려면 하이픈(-)을 사용하라.
  • e.g. /posts/{id}/long-comments
• 특정 Resource 하나를 가져올때에는 URI에 해당 Resource의 Identifier를 포함하여 표현한다.
  • e.g. /posts/{id}
• Resource 목록의 페이징(Paging), 필터링(Filtering), 정렬(Sorting), 검색(Searching)을 통해 정보를 가져올시, Path Variable을 활용gks다.
  • e.g. /posts?page=12 , /posts?order=latest
• 적절한 Status Code를 응답한다.
  • 종류
    1. 1XX (Informational) : 요청이 수신되어 처리중
    2. 2XX (Successful) :요청 정상 처리
       • 200 OK : 요청 성공
       • 201 Created : 요청 성공해서 새로운 리소스 생성
       • 202 Accepted : 요청이 접수 되었으나 처리가 완료되지 않았음
       • 204 No Content : 서버가 요청을 성공적으로 수행했으나, 응답 페이로드 본문에 보낼 데이터 없음
    3. 3XX (Redirection) : 요청 완료를 위한 추가행동 필요 : 보통 리다이렉션(넘기기)로 처리
       • 301 Moved Permanently : 리다이렉트시 요청 메서드가 GET으로 변하고, 본문이 제거될 수 있음
       • 302 Found : 리다이렉트시 요청 메서드가 GET으로 변하고, 본문이 제거될 수 있음
       • 303 See Other : 리다이렉트시 요청 메서드가 GET으로 변경
       • 304 Not Modified : 캐시를 목적으로 사용
       • 307 Temporary Redirect : 리다이렉트시 요청 메서드와 본문 유지(요청 메서드를 변경하면 안된다.)
       • 308 Permanent Redirect : 리다이렉트시 요청 메서드와 본문 유지(처음 POST를 보내면 리다이렉트도 POST 유지)
    4. 4XX (Client Error) : 클라이언트 오류, 잘못된 문법등으로 서버가 요청을 수행할 수 없음
       • 400 Bad Request : 클라이언트가 잘못된 요청을 해서 서버가 요청을 처리할 수 없음
       • 401 Unauthorized : 클라이언트가 해당 리소스에 대한 인증이 필요함
       • 403 Forbidden : 서버가 요청을 이해했지만 승인을 거부함
       • 404 Not Found : 요청 리소스를 찾을 수 없음
    5. 5XX (Server Error) : 서버 오류, 서버가 정상 요청을 처리하지 못함
       • 500 Internal Server Error : 서버 문제로 오류 발생, 애매하면 500 오류
       • 501 Not Implemented : 서버에 해당 기능이 없음
       • 502 Bad Gateway: 게이트웨이(서로 다른 프로토콜을 연결해주는 장치)가 잘못된 프로토콜을 연결하거나, 어느쪽 프로토콜에 문제가 있어 통신이 제대로 되지 않은 상황
       • 503 Service Unavailable : 서비스 이용 불가 (서버가 다운되었을때)

 

---

REST에 대해 적당히 이해한 것 같은데, 이것을 바탕으로 과연 내일,,, API 명세서를 작성하고, 구현을 해볼 수 있을까? 부디... 성공적으로...... 마무리해서 내일 포스트 할 수 있길... 바란다...