REST API 정리

REST API란,

REST란, REpresentational State Transfer의 약자이다. 2000년도에 로이 필딩(Roy Fielding)의 박사학위 논문에서 최초로 소개되었다. 그는 웹(HTTP) 설계의 우수성에 비해 제대로 사용하지 못해 웹의 장점을 최대한 활용할 수 있는 아키텍처로 REST를 발표했다.

REST의 구성

• 자원(Resource) - URI
• 행위(Verb) - HTTP Method
• 표현(Representations)

REST 특징

1. Uniform Interface
   • URI로 지정한 리소스에 대한 조작은 통일되고, 한정적인 인터페이스로 수행하는 아키텍처 스타일이다.
2. Stateless
   • REST는 작업을 위한 상태 정보를 따로 저장하거나 관리하지 않는다. 세션이나 쿠키를 별도로 저장하거나 관리하지 않기 때문에, API 서버는 들어오는 요청만을 단순히 처리한다.
3. Caching
   • REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹 표준을 그대로 사용하는 것이다. 그래서 HTTP가 가진 캐싱 기능이 적용될 수 있다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.
4. Client-Server
   • REST 서버는 API를 제공하고, 클라이언트는 사용자 인증이나 Context(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에, 서버/클라이언트 간 의존성이 줄어든다.
5. Hierarchical System
   • REST 서버는 다중 계층으로 구성될 수 있으며, 보안, 로그밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고, Proxy, Gateway 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.
6. Code on demand
   • 서버가 네트워크를 통해 클라이언트에 프로그램을 전달하면, 그 프로그램이 클라이언트에서 실행될 수 있어야 한다. 다만, 이 제약조건은 필수가 아니다.

REST API 디자인 가이드

REST API 중심 규칙

1. 리소스와 행위를 명시적이고 직관적으로 분리한다.
   • 리소스는 URI로 표현되는데, 리소스가 가리키는 것은 명사로 표현되어야 한다.
   • 행위는 HTTP Method로 표현하고, GET(조회), POST(생성), PUT(기존 Entity 전체 수정), PATCH(기존 Entity 일부 수정), DELETE(삭제)를 분명한 목적으로 사용한다.
2. Message는 Header와 Body를 명확하게 분리해서 사용한다.
   • Entity에 대한 내용은 body에 담는다.
   • 애플리케이션 서버가 행동한 판단의 근거가 되는 컨트롤 정보인 API 버전정보, 응답받고자하는 MIME 타입 등은 Header에 담는다.
   • Header와 Body는 HTTP Header와 HTTP Body로 나눌 수 있고, HTTP Body에 들어가는 JSON 구조롤 분리할 수도 있다.
3. API 버전을 관리한다.
   • 환경은 항상 변하기 때문에 API의 Signature가 변경될 수 있음을 유의해야한다.
   • 특정 API를 변경할 때는 반드시 하위호환성을 보장해야한다.
4. 서버와 클라이언트가 같은 방식을 사용해서 요청하도록 한다.
   • 브라우저는 form-data 형식의 submit으로 보내고, 서버에서는 json형태로 보내는 식의 분리보다는 서버/클라이언트 모두 json으로 보내거나 form-data로 보내야 한다.
   • URI는 플랫폼에 중립적이어야 한다.

REST API 설계 시, 주의할 점

1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
3. 하이픈(-)은 URI 가독성을 높이는데 사용한다.
4. 밑줄(_)은 URI에 사용하지 않는다.
5. URI 경로에는 소문자가 적합하다.
6. 파일 확장자는 URI에 포함시키지 않는다.

참고

Interview_Question_for_Beginner/Development_common_sense at master · JaeYeopHan/Interview_Question_for_Beginner

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

바쁜 개발자들을 위한 REST 논문 요약

REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁