RESTful API

RESTful API는 월드 와이드 웹(www)과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식으로 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반에 대한 패턴이라고 정의되어 있다.

여기서 REST란 REpresentational State Transfer의 약자이다. "REST는 디자인 패턴이다." 혹은 "REST는 아키텍처다."라는 의견이 나뉘는데 결론부터 말하면 REST는 아키텍처이다. 좀 더 정확한 표현으로는 Resource Oriented Architecture이다. API 설계의 중심에 자원이 있고 HTTP Method를 통해 자원을 처리하도록 설계하는 것이다.

RESTful API 구성

1. 자원 (Resource) - URI
   • GET /user/1/info
2. 행위 (Verb) - HTTP Method
   • GET, POST, PUT/PATCH, DELETE
3. 표현 (Representations)

REST 6가지 원칙

Uniform Interface (인터페이스 일관성)

일관적인 인터페이스로 분리되어야 한다.

Stateless (무상태성)

각 요청 간 클라이언트의 context가 서버에 저장되어서는 안된다.

Cacheable (캐시 처리 가능)

WWW에서와 같이 클라이언트는 응답을 캐싱할 수 있어야 한다.
-> 잘 관리되는 캐싱은 클라이언트-서버 간 상호작용을 부분적으로 또는 완전하게 제거하여 scalability와 성능을 향상시킨다.

Client-Server (클라이언트 - 서버 구조)

아키텍처를 단순화시키고 작은 단위로 분리함으로써 클라이언트-서버의 각 파트가 독립적으로 개선될 수 있도록 해준다.

Hierachical System (계층화)

클라이언트는 보통 대상 서버에 직접 연결되었는지 중간 서버를 통해 연결되었는지 알 수 없다. 중간 서버는 Load balancing 기능이나 공유 캐시 기능을 제공함으로써 시스템 규모 확장성을 향상시키는데에 유용하다.

Code on demand (Optional)

자바 애플릿이나 자바 스크립트의 제공을 통해 클라이언트가 실행할 수 있는 로직을 전송하여 기능을 확장시킬 수 있다.

Design RESTful API

RESTful API를 디자인하는 것은 무엇을 의미하는지 알아보았다.

1. 리소스와 행위를 명시적이고 직관적으로 분리한다.
   - 리소스는 URI로 표현되는데 리소스가 가리키는 것은 명사로 표현되어야 한다. 즉 URI는 정보의 자원을 표현해야 한다. (명사로)
   -> GET /user/look (X) look은 동사이므로 X
   GET /user/info (O) info는 information 명사이므로 O
   - 행위는 HTTP Method로 표현하고, GET(조회), POST(생성), PUT(기존 entity 전체 수정), PATCH(기존 entity 일부 수정), DELETE(삭제)을 분명한 목적으로 사용한다.

2. Message는 Header와 Body를 명확하게 분리해서 사용한다.

   • Entity에 대한 내용은 body에 담는다.
     -> 회원 입력 정보와 같은 내용은 body에 담아 전송
   • 애플리케이션 서버가 행동할 판단의 근거가 되는 컨트롤 정보인 API 버전 정보, 응답받고자 하는 MIME 타입 등은 header에 담는다.
     -> JWT token과 같은 내용은 header에 담아 전송
   • header와 body는 http header와 http body로 나눌 수 있고, http body에 들어가는 json 구조로 분리할 수 있다.

3. API 버전을 관리한다.

   • 환경은 항상 변하기 때문에 API의 signiture가 변경될 수 있음에 유의해야한다.
   • 특정 API를 변경할 때는 반드시 하위호환성을 보장해야 한다.

4. 서버와 클라이언트가 같은 방식을 사용해서 요청하도록 한다.

   • 브라우저는 form-data 형식의 submit으로 보내고, 서버에서는 json형태로 보내는 식의 분리보다는 json이나 form-data 중 하나로 통일한다.
   • 즉, URI가 플랫폼 중립적이어야 한다는 의미이다.

RESTful API 장점

1. Open API를 제공하기 쉽다.
   • 주어진 형식에 맞게 작성되기 때문
2. 멀티플랫폼 지원 및 연동이 용이하다.
   • 주어진 형식에 맞게 작성되기 때문
3. 원하는 타입으로 데이터를 주고 받을 수 있다.
4. 기존 웹 인프라(HTTP)를 그대로 사용할 수 있다.
   • URI 작성을 추가로 하여 HTTP를 그대로 사용

RESTful API 단점

1. 사용할 수 있는 메소드가 4가지밖에 없다.
   • GET (조회)
   • POST (생성)
   • PUT/PATCH (수정)
   • DELETE (삭제)
2. 분산환경에는 부적합하다.
3. HTTP 통신 모델에 대해서만 지원한다.

Reference

REST API 제대로 알고 사용하기 - TOAST