REST API 에 대한 일반적인 인식
- URI 를 통해 자원을 지정
- HTTP 메서드 -> 자원에 대한 행위를 표현
:: CRUD ::
POST /user
GET /user/1
PUT /user/1
DELETE /user/1
로이 필딩의 REST API
REST - 위키백과, 우리 모두의 백과사전
위키백과, 우리 모두의 백과사전. 대한민국의 힙합 음악가에 대해서는 R-EST 문서를 참고하십시오. REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프
ko.wikipedia.org
REST 아키텍처 스타일에 부합하는 API
REST 아키텍처에 적용되는 6가지 제한 조건
- Client-Server
- Stateless
- Cache
- Uniform Interface
- Layered System
- Code-On-Demand
Uniform Interface
4가지 제약 조건이 존재한다.
- 자원의 식별 (identification of resource)
- 표현을 통한 자원의 조작 (manipulation of resources through representations)
- 자기 서술적 메시지 (self-descriptive messages)
- 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/