REST
REST(Representational State Transfer)는 소프트웨어 개발 아키텍처 스타일이며, HTTP 프로토콜을 준수합니다.
자원(resource)을 이름(representation)으로 구분하여 해당 자원의 정보(state)를 주고 받는 모든 것을 의미한다.
웹에서 데이터를 HTTP 위에서 별도의 전송 계층 없이 전송하기 위한 인터페이스로 자원을 이름으로 구분하여 자원의 상태를 주고받는 모든 행위를 의미한다.
즉 HTTP URI를 통해 자원을 명시(Representation)하고 HTTP Method를 통해 해당 자원의 CRUD Operation을 적용하는 것으로 네트워크 상 클라이언트 서버 간 통신 방식 중 하나이다.
REST API?
REST API는 REST 원칙을 기반으로하는 API를 말한다.
RESTful
REST 의 원리를 따르는 시스템을 말한다.
REST API 의 설계 규칙을 잘 지킨 시스템을 RESTful 하다고 할 수 있다.
왜 쓸까?
-
(확장성) server, client 책임을 명확하게 분리하여 독립적으로 확장할 수 있도록 한다.
-
(사용성) 이름과 메소드만 봐도 의도를 명확하게 알 수 있어 관리와 사용이 쉽다.
-
(범용성) HTTP 표준이므로 별도의 인프라 구축이 필요 없고 HTTP 프로토콜을 따르는 모든 플랫폼에서 사용할 수 있다.
REST 원칙
Layered System
API 서버는 순수하게 비즈니스 로직을 담당하며 클라이언트는 API 서버만 호출한다.
REST 서버는 다중 계층으로 구성 가능하다. 앞 단에 보안,암호화,인증 등의 계층을 추가하여 구조의 유연성을 줄 수 있다.
Cacheable
HTTP 프로토콜을 그대로 사용하기 때문에 HTTP의 캐싱 기능을 적용할 수 있다.
필요시 캐싱을 통해 응답시간, 자원 이용률을 향상시킬 수 있다.
Stateless
HTTP가 Stateless이기 때문에 REST역시 Stateless하다.
클라이언트 상태를 서버가 알지 못하며 서버는 각 요청을 별개의 것으로 인식하고 단순히 요청에 대한 응답을 처리한다.
Server-Client
자원을 가진 계층이 Server이며 서버는 API를 제공하고 비즈니스 로직 처리를 책임진다.
Uniform Interface
클라이언트와 서버는 모든 통신에 항상 동일한 프로토콜을 사용하며 HTTP 표준 프로토콜을 따르는 모든 플랫폼에서 사용할 수 있어야 한다.
URI로 지정한 자원에 대한 조작을 일관성있고 한정적인 인터페이스로 수행한다.
REST API 구성 요소
Resource
모든 자원에는 고유 식별자가 있고 서버에 존재하며 자원의 구별을 URI로 한다.
'게시글' 이라는 자원에서 'post_id'를 가지는 것 하나를 구별
/posts/[post_id]Verb
Http Method를 사용해 행위를 표현한다.
'게시글' 이라는 자원에서 'post_id'를 가지는 것 하나를 구별한 것을 '가져온다'
[GET] /posts/[post_id]Representation
클라이언트가 자원 상태 조작을 요청하면 서버는 이에 대한 적절한 응답을 표현한다.
JSON 또는 XML을 통해 보통 주고받는다.
'게시글' 이라는 자원에서 'post_id'를 가지는 것 하나를 구별한 것을 '가져온다'
[GET] /posts/[post_id]
status: 200
response body: {
postId: 1,
postTitle: 'hello',
postBody: 'eagagagagaga',
createdAt: '2023-03-27'
}일반적인 REST API 설계 규칙
URI는 소문자로 작성하며 공백이나 언더바(_) 대신 하이픈(-)을 사용한다
가독성을 위해 언더바 대신 하이픈을 사용한다. 언더바는 클라이언트에 따라 잘 안보일 수 있다.
URI는 경로의 명사(자원)만을 표현하며 동사를 사용하지 않는다.
GET /members/update/2 => bad
PUT /members-update/2 => bad
PUT / members/2 => goodHttp Method로 충분히 표현할 수 있는 행위를 URI에 넣지 않을 것
자원의 계층관계를 나타내는 것에 슬래시(/)를 사용한다
GET /users/123/orders/456쿼리스트링을 사용해 필터링, 페이징, 정렬 같은 기능을 제공한다
GET /posts?page=1&size=10적절한 http status code를 사용해 요청에 대한 결과를 나타낸다.
1xx : 전송 프로토콜 수준의 정보 교환
2xx : 클라어인트 요청이 성공적으로 수행됨
3xx : 클라이언트는 요청을 완료하기 위해 추가적인 행동이 필요
4xx : 클라이언트의 잘못된 요청
5xx : 서버 오류자주 쓰이는 status code
200 OK: 서버가 요청을 성공적으로 처리
201 Created: 서버가 새로운 자원 생성을 성공 (Post)
204 No_Content: 서버가 요청을 성공했고 반환할 데이터가 없음 (Delete)
302 Found: 요청한 리소스가 다른 URL에 있음
400 Bad_Request: 클라이언트의 요청이 유효하지 않음(이유 필요)
401 UnAuthorized: 클라이언트가 인증되지 않음
403 Forbidden: 클라이언트가 요청한 자원에 접근 권한이 없음
404 Not_Found: 클라이언트가 요청한 자원이 서버에 없음
405 Method_Not_Allowed: 요청한 HTTP 메소드가 서버에서 허용되지 않음
429 Too_Many_Request: 클라이언트가 너무 많은 요청을 보내 서버에서 요청을 일시적으로 제한
500 Internal_Server_Error: Http Method
GET
URI에 명시된 리소스를 조회한다.
POST
클라이언트의 요청 데이터를 통해 리소스를 생성한다.
PUT
리소스를 수정한다.
PATCH
리소스의 일부를 수정한다.
HEAD
리소스의 실제 데이터를 제외하고 메타데이터를 조회한다.
OPTIONS
서버가 지원하는 메소드 종류를 확인한다.
가장 중요한 것은
기본적으로 구체적인 rest api 설계 방법이 정해져있는 것은 아니기 때문에
개발 시 다음과 같은 원칙을 지켜 restful을 준수해야 할 것 같다
URI를 통해 리소스를 잘 표현하자
자원에 대한 행위를 HTTP METHOD를 통해 할 수 있게 의도하자
요청에 대해 일관성 있는 형태로 상황에 맞는 응답을 표현하자
Reference
