REST API란?

REST API 에 대한 일반적인 인식

- URI 를 통해 자원을 지정
- HTTP 메서드 -> 자원에 대한 행위를 표현
:: CRUD ::
POST /user
GET /user/1
PUT /user/1
DELETE /user/1

 

로이 필딩의 REST API

REST - 위키백과, 우리 모두의 백과사전

 

REST 아키텍처 스타일에 부합하는 API

REST 아키텍처에 적용되는 6가지 제한 조건

1. Client-Server
2. Stateless
3. Cache
4. Uniform Interface
5. Layered System
6. Code-On-Demand

 

Uniform Interface

4가지 제약 조건이 존재한다.

1.  자원의 식별 (identification of resource)
2. 표현을 통한 자원의 조작 (manipulation of resources through representations)
3. 자기 서술적 메시지 (self-descriptive messages)
4. HATEOAS (hypermidia as the engine of application state)

 

1. 자원의 식별

자원

• 이름을 지닐 수 있는 모든 정보
• 개념적인 대상
• ex) 문서, 이미지, 자원들의 집합, 실존하는 대상 등

 

자원은 객체

• 상태는 변화가능
• 변하지 않는 식별자 필요

 

URI 를 통해 자원을 식별해야 한다!

 

2. 표현을 통한 자원에 대한 조작

표현

• 특정한 상태의 자원에 대한 표현
• 자원은 다양한 방식으로 표현 가능
• ex) 문서, 파일, HTTP 메시지 엔티티 등

 

REpresentational State Transfer

표현된 (자원의) 상태 전송

• 자원의 현재 상태
• 자원의 기대되는 상태

 

3. 자기 서술적 메시지

메시지는 스스로에 대해 설명해야 한다!

-> 누구에게? 클라이언트와 서버에게!

클라이언트와 서버 사이의 컴포넌트들은 메시지의 내용을 참고하여 적절한 작업을 수행

 

Host 헤더

Host 헤더에 도메인명 기재 필요!

도메인명 정보의 필요성 - 가상호스트 문제

• 하나의 IP 주소에 복수의 도메인명이 존재 가능
• IP 주소만으로는 요청 대상을 찾아낼 수 없다.

 

캐쉬

캐쉬 관련 헤더를 통한 캐쉬 전략 지정

개별 요청에 대한 응답을 캐쉬에 넣는 경우,

일정 기간 동안 서버까지 요청을 보내지 않고서 응답를 가져올 수 있다.

서버는 클라이언트가 컴포넌트롤 통해 필요한 응답을 가져갈 수 있도록 적절한 정보를 배치

 

4. HATEOAS (hypermidia as the engine of application state)

하이퍼미디어를 통한 앱 상태 변경

 

REST API 여야 하는가?

필딩은 말했다.

시스템을 통제할 수 있다고 생각한다면
REST 에 시간을 낭비하지 말라!

논문에 언급된 내용 일부

- Uniform Interface 제약조건은 비효율적
- 애플리케이션에 필요한 정보가 아니라 표준화된 형식으로 데이터를 전달
- 상황에 따라 최적이 아닐 수 있음

 

API 설계의 방향성

• 진짜 REST API 만들기 (aka. RESTful API)
• REST 스타일의 API 만들기 (aka. HTTP API)
• 다른 API 표준 선택하기 (e.g, GraphQL API)

 

진짜 REST API 만들기

Reference

- 이응준 : 그런 REST API 로 괜찮은가
- 로이필딩 : 박사 학위 논문 챕터5, 챕터 6 (https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
- Microsoft : RESTful web API design https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
- Spring 공식 문서 :  Spring HATEOAS (https://spring.io/projects/spring-hateoas)

 

REST 스타일의 API 만들기

Reference


- Microsoft : https://github.com/microsoft/api-guidelines

• REST 제약조건을 부분적으로 준수
  • ex) URI 를 통한 자원의 식별
• HTTP 스펙을 적절하게 활용
• API 설계에 관한 컨벤션 참고

 

주의 ! 이런식으로 작성된 API  를 무분별하게 REST API 라 칭하지 말자 !

 

다른 API 표준 선택하기

Reference

 Spring 공식 문서 : https://spring.io/projects/spring-graphql
GraphQL 공식 문서 : https://graphql.org/