Rest 구성
- 자원(RESOURCE) – URI
- 행위(Verb) – HTTP METHOD
- 표현(Representations)
Rest API 탄생 배경
Rest API(Representational State Tranfer)는 2000년도 로이 필딩의 박사 학위 논문에서 최초로 소개되었다. HTTP 설계의 우수성에 비해 제대로 사용되지 못하는 모습이 안타까워 만든 웹 아키텍처이다.
REST의 특징
1. Uniform(유니폼 인터페이스)
Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일이다.
2. Stateless(무상태성)
REST는 무상태성 성격을 갖는다. 작업을 위한 상태 정보를 따로 저장하지 않고 관리하지 않는다. 세션 정보 및 쿠키 정보를 별도로 저장하지 않기 때문에 API 요청에 대한 단순 처리만 하면 된다. 이를 통해 서비스의 자유도를 높이고 서버에 불필요한 정보를 관리하지 않아 구현이 단순해진다.
3. Cacheable(캐시 가능)
REST의 가장 큰 특징 중 하나는 HTTP의 기존 인프라를 그대로 활용이 가능하다. 그중 캐싱 기능 또한 적용 가능하다. Last-Modified 태그, E-Tag를 사용하여 캐싱 구현이 가능하다.
4. Selft-desccriptiveness(자체 표현 구조)
REST API 메시지만 보고도 사용자가 쉽게 이해할 수 있는 자체 표현 구조를 가지고 있다.
5. Client-Server 구조
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 콘텍스트 등을 직접 관리하는 구조로 역할이 구분되어 개발해야 할 내용이 명확하고 서로 간 의존성이 줄어든다.
6. 계층형 구조
REST 서버는 다중 계층으로 구성 가능하여 보안, 로드밸런싱, 암호화 계층 등을 추가해 구조상의 유연성을 둘 수 있다.
REST API 장단점
장점
- HTTP 프로토콜 인프라를 그대로 사용하여 별도 인프라 구축이 필요 없다.
- HTTP 프로토콜의 장점을 그대로 가져간다.
- HTTP 프로토콜을 따르는 모든 플랫폼에 적용 가능
- Hypermedia API 기본을 충실히 지키고 범용성을 보장
- 의도하는 바를 쉽게 파악할 수 있다.
- 여러 서비스 디자인에서 생길 수 있는 문제를 최소화
- 서버와 클라이언트 역할을 명확하게 분리
단점
- 표준이 존재하지 않는다.
- 사용할 수 있는 메서드가 4가지 밖에 안된다.
- 브라우저로 테스트를 많이 하면 Header 값 수정이 어려워 테스트에 어려움을 느낄 수 있다.
- 구형 브라우저에서 지원하지 않는 PUT, DELETE가 있다.
REST API 디자인 가이드
API를 디자인할 때 두 가지만 기억하면 된다.
1. URI는 정보의 자원을 표현해야 한다.
- resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
- resource의 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
- resource의 컬렉션 이름으로는 복수 명사를 사용해야 한다.
- resource의 스토어 이름으로는 복수 명사를 사용해야 한다.
2. 자원에 대한 행위는 HTTP Method로 표현한다.
- URI에 HTTP Method가 들어가면 안 된다.
- URI에 행위에 대한 동사 표현이 들어가면 안 된다.
- 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
각 Method 별 알맞은 역할
- POST : POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
- GET : GET를 통해 해당 리소스를 조회한다. 자세한 정보도 가져온다.
- PUT : PUT를 통해 해당 리소스를 수정한다.
- DELETE : DELETE를 통해 리소스를 삭제한다.
URI 설계 시 주의사항
- 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
- URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
- 하이픈(-)은 URI 가독성을 높이는 데 사용한다.
- 밑줄(_)은 URI에 사용하지 않는다.
- URI 경로에는 소문자가 적합하다.
- 파일 확장자는 URI에 포함시키지 않는다.
리소스 간의 관계 표현법
GET : /users/{userid}/devices - 관계가 있을 때 표현 방법 예시
관계명이 복잡하다면 아래와 같이 표현한다.
GET : /users/{userId}/likes/devices - 관계명이 애매하거나 구체적 표현이 필요할 때
자원을 표현하는 Collection과 Document
Collection과 Document를 표현할 수 있으면 URI 설계가 한층 쉬워진다. 컬렉션과 도큐먼트는 모두 리소스로 표현할 수 있고 URI에 표현된다.
/sports/soccer - 복수형을 통해 sports 콜렉션과 soccer 도큐먼트를 표현했다.
응답상태코드
1xx : 전송 프로토콜 수준의 정보 교환
2xx : 클라어인트 요청이 성공적으로 수행됨
3xx : 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
4xx : 클라이언트의 잘못된 요청
5xx : 서버쪽 오류로 인한 상태코드
참고
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://meetup.toast.com/posts/92