API 설계 관련해서 리뷰를 하다 보면 항상 RESTful API가 맞나에 대한 의문이 많아서 정리해 보았다.
REST란?
REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것
이 뜻에서 볼 수 있듯이 REST API는 [ 자원 - URI, 행위 - http method, Representation(표현) - payload ]로 구성되어 있다.
REST 특징 ( REST에 적용되는 6가지 제한 조건 )
인터페이스 일관성
리소스에서 수행할 수 있는 작업의 균일한 인터페이스를 정의한다.GET, POST, PUT, DELETE와 같은 HTTP Method를 사용해서 구현된다.
무상태(Stateless) 통신
클라이언트 -> 서버 요청은 서버가 이해하고 처리하는데 필요한 모든 정보가 포함되어야 한다.
서버는 요청 간에 클라이언트에 대한 상태를 유지하지 않는다.
이렇게 해서 확장성이 단순화되고 요청을 독립적으로 처리할 수 있다.
캐시 가능(Cacheable)
HTTP의 웹 표준을 그대로 사용하기 때문에 웹에서 사용하는 기존 기능들을 그대로 활용할 수 있다.
따라서 HTTP의 캐싱이 적용될 수 있다. last-modified 태그나 E-tag를 이용해서 캐싱 구현이 가능하다.
계층화(Layered System)
서버에서 다른 서버로 전달하는 것처럼 여러 계층으로 구성될 수 있다.
이때 로드 밸런싱이나 암호화 계층, proxy 등 을 추가할 수 있다.
물론 이 계층들은 클라리언트에 보이지 않는 상태로 유지된다.
Code on demand
서버에서 소프트웨어 프로그래밍 코드를 클라이언트에 전송해서 클라이언트 기능을 일시적으로 확장할 수 있다.
예를 들어, 웹사이트에서 양식을 작성하면 브라우저는 잘못된 양식에 대한 에러를 표시할 수 있다.
Client - Server 구조
클라이언트(요청 시스템)와 서버(응답 시스템)를 분리해서 독립적으로 발전시킬 수 있다.
클라이언트는 UI와 UX를 담당하고 서버는 데이터 저장 및 처리를 한다.
REST 가이드
1. 자원 식별 : 우선 API가 공개할 리소스를 결정한다.
2. URI 정의 : 각 리소스에 고유한 URI를 할당한다.
3. HTTP 메서드 선택 : 메서드를 정의한다.
GET : 리소스나 리소스 리스트를 검색
POST : 새 리소스 생성
PUT : 완전한 표현(리소스를 만드는데 필요한 모든 데이터)으로 기존 리소스 업데이트
PATCH : 리소스를 부분적으로 변경해서 업데이트
DELETE : 리소스 제거
4. 요청 처리 구현
5. HTTP 상태 코드 사용
일반적인 코드들만 정리하면 아래와 같다.
200 : 정상
201 : 생성됨
400 : 잘못된 요청
404 : 찾을 수 없음
500 : 내부 서버 에러
6. 데이터 표현 : API 응답에서 리소스를 표현하기 위한 형식 결정 -> 일반적으로 JSON 사용
7. 버전 관리 : API가 업데이트되는 것이 예상될 경우 URI에 버전번호를 넣는 등의 버전 관리를 한다.
8. 인증 및 권한 부여
9. 문서 : API에 대한 문서를 쓴다.
10. 테스트 : 철저히 테스트해서 예상대로 작동하고 요구사항을 충족하는지 확인한다.
REST는 소프트웨어 아키텍처의 한 형식이고 표준이 존재하지 않는다.
각 조직의 환경과 성향에 따라 원칙을 어느 정도 따르고 모범 사례들을 보며 그것을 지키면 개발자가 쉽게 사용할 수 있는 잘 설계되고 직관적인 API를 만드는데 큰 도움이 된다.
REST구조를 처음으로 소개한 로이필딩의 논문 링크를 첨부하면서 글을 마무리하겠다.
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)
proxy CERN Proxy, Netscape Proxy, Gauntlet
www.ics.uci.edu
댓글