REST
REST는 2000년에 Roy Fielding의 논문으로부터 처음 세상에 나오게 되었다.
REST는 REpresentational State Transfer의 약자이다.
이는 분산 하이퍼미디어(ex: Web) 시스템을 위한(웹 서비스에서의 통신을 위한) 아키텍처 스타일이다.
이러한 REST의 6가지 원칙을 따르는 API를 RESTful API라고 하며, 6가지 원칙은 다음과 같다.
REST의 6가지 원칙
-
Client-Server: REST 서버와 클라이언트의 역할은 명확히 구분되어 있기때문에, 각각 개발해야 할 내용이 명확하지고 서로간의 의존성이 줄어든다.
-
Stateless: REST는 작업을 위한 상태정보를 따로 저장, 관리하지 않는다. 그렇기에 API 서버는 요청에 대한 처리만 하면 되며, 이에 따라 서비스의 자유도는 높아지고 구현이 단순해진다.
-
Cacheable: REST는 HTTP Porotocol을 그대로 사용하기 때문에 웹에서 사용하는 인프라를 그대로 사용할 수 있다. 그렇기에 캐싱 기능을 적용할 수 있으며, 적용을 위해 Last-Modifined 태그나 E-Tag를 이용하면 된다.
-
Uniform Interface: URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
-
Layered System: REST 서버는 다중 계층으로 구성될 수 있고 보안, 로드 밸런싱, 암호화 계층을 추가할 수 있으며, Proxy, Gateway 같은 네트워크 기반 중간매체를 사용할 수도 있다.
-
Code on demand(Optional): REST를 사용하면 applet이나 스크립트 형태의 코드를 다운로드하고 실행해 클라이언트 기능을 확장할 수 있다. 이는 사전 구현 기능 수를 감소시켜주어 클라이언트를 단순화한다.
위 원칙을 준수한다면 RESTful API라고 할 수 있겠다.
그런데, 이 6가지 원칙에 대한 이해를 했다해도 막상 REST API를 디자인 하려하면 막막해진다.
아래는 이에 대한 디자인 가이드라인이다.
REST API 디자인가이드
중심 규칙
1. Resources
- 리소스 설명 시 가능한 한 동사가 아닌 명사를 사용한다.
- Get /users
- Get /users/1
- Patch /workspaces/2
- Post /workspaces/2/messages
- URI case는 CamelCase, snake_case, spinal-case 중 가능한 한 spinal-case를 사용한다.
- HTTP Methods
- REST는 HTTP 프로토콜을 사용하며, RESTful API는 HTTP 메서드를 사용해 리소스에 어떠한 액션을 수행할건지를 나타낸다.
- HTTP 메서드의 종류 및 의미는 다음과 같다.
- GET: 리소스를 가져오는데 사용된다.- HEAD: GET과 동일하나, status line과 header section만 전송한다.
- POST: 서버에 데이터를 전달한다.
- PUT: 리소스를 업데이트 한다.
- PATCH: 리소스의 일부를 업데이트 한다.
- DELETE: 리소스를 삭제한다.
- HTTP Headers
- 요청, 응답, Body에 대한 정보를 제공한다.
- HTTP 헤더는 다음과 같은 4가지 타입이 있다.
- General Header: 요청 및 응답 메시지 모두 포함.- Client Request Header: 요청 메시지에만 포함.
- Server Response Header: 응답 메시지에만 포함.
- Entity Header: Body에 대한 메타 정보와 관련된 헤더.
- Query Patameters
- Paging: 리턴 데이터 양이 많거나 예측이 어려운 경우 페이징 처리를 하는것이 좋다.
- Filter: 속성에 기대값을 지정해 리소스를 필터링 한다. 한번에 여러 속성으로 필터링 할 수도 있다.
- Sorting: 리소스를 정렬한다. 정렬을 수행할 속성 이름을 포함한다.
- Searching: Filter와 비슷하지만, 정확하게 일치하는 것이 아닌 대략적으로 일치하는 것을 필터링한다.
- Status Code
- 200: OK
- 201- CREATED: 리소스 생성
- 204- NO CONTENT: 리소스가 성공적으로 삭제 혹은 응답 본문 없는 경우
- 304- NOT MODIFIED: 데이터가 변경되지 않음(캐시 데이터 사용 권장)
- 400- BAD REQUEST: 요청 유효하지 않음
- 401- UNAUTHORIZED: 사용자 인증 필요
- 403- FORBIDDEN: 리소스에 대한 접근 허용되지 않음
- 404- NOT FOUND: 리소스 존재하지 않음
- 500- INTERNAL SERVER ERROR: 요청 처리 중 알 수 없는 에러 발생(보통 서버쪽 에러)
URI 설계 시 주의점
1. /는 계층 관계를 나타내는 데 사용
https://localhost:3000/cats/russianblue https://localhost:3000/dogs/husky
-
URI 마지막에
/포함 불가
https://localhost:3000/cats/russianblue/ -
가독성을 높이기 위해
-사용(URI가 긴 경우) -
_은 사용 불가 -
URI은 소문자로 작성
-
URI에 파일 확장자를 포함하지 않음
- Accept Header를 사용하도록 한다.
GET /cats/russianblue/3/picture HTTP/1.1 Host: restapi.test.com Accept: image/jpg
- Accept Header를 사용하도록 한다.
리소스 간 관계 표현
Case 1) 리소스 간 관계가 복잡하지 않을 경우(보통 has 관계를 표현할 때)
GET : /users/:id/pets
Case 2) 리소스 간 관계가 복잡한 경우(관계명 모호, 구체적 표현)
GET : /users/:id/supports/pets
Collection과 Document
- Collection은 문서 또는 객체들의 집합
- Document는 하나의 문서 또는 객체
- 이 둘은 모두 리소스에 해당되며 URI에 표현됨
https://localhost:3000/restapi.test.com/workspaces/1/users/3
- 위 예에서 Collection은 workspaces, users이고, Document는 1번 워크스페이스와 3번 유저이다.
- 위처럼 Collection과 Document 사용 시 단수, 복수를 쓴다면 보다 더 가독성이 좋은 URI를 설계할 수 있다.
참고
https://restfulapi.net/
https://meetup.toast.com/posts/92
https://gunju-ko.github.io/spring/2020/09/15/Rest-API-%EB%94%94%EC%9E%90%EC%9D%B8-%EA%B0%80%EC%9D%B4%EB%93%9C.html
