REST API 란?

REST API

해당 포스팅의 목적

• URI를 통해 하나의 자원으로 표현하는 방식으로 스네이크 케이스, 카멜케이스 처럼 개발자들간의 암묵적인 약속을 아는게 중요하다고 생각한다.
• 이전까지는 그저 넒은범위의 Web API 혹은 RESTful 하지 못한 REST API를 개발해온것 같다.(= HTTP API)

REST API란?

• REST API는 특정 기술이 아니다.
• REST API에서 데이터는 Resource라 표현한다. 이런 Resource는URI 로 표현한다. 이런 데이터가 복수일땐 Collection, 그중 하나를 선택(단수)일땐 element라 부른다.
  • ex) https://naver.com/boards → collections  https://naver.com/boards/1 → element : Id가 1인 board!
  • URI에 동사를 넣지 않는다.(행위는 HTTP메소드)
• 표현된 URI는 가공할수있어야 하는데, 이는 HTTP 메소드를 통해 이루어진다.
  • C : Post
  • R : Get
  • U : Put(전체) | Patch(일부)
  • D : Delete
• 응답에는 200, 201등의 응답코드가 포함되어야 한다!
• REST API는 URI로 자원을 식별하고, HTTP 메소드로 행위를 표현하며, 응답코드(Http Status)로 응답한다!

잘 지켜지지 않는 사항들

REST API라고 부르지만, 사실 잘 지켜지지 않는 사항들이 있다. 대부분은 위에 기술한 내용들만 충족하지만, 사실 REST API로 간주되려면 더 필요한 사항들이 있다. REST API로 간주되기 위한 원칙들을 알아보고, 위 기술한 내용이 어떤 항목은 충족하고, 또 충족하지 않는지 알아보자.

1. 클라이언트-서버 및 리소스 로 구성되어있으며, HTTP를 통해 요청이 들어오는 아키텍처
2. Stateless 한 아키텍처
3. 클라이언트-서버 간 상호작용을 최소화 할수있는 캐시가능 데이터
4. 정보가 표준 형식으로 전송되기 위한 통합 인터페이스
   1. 요청된 리소스가 식별가능(URI)하며 클라이언트에 전송된 표현과 분리
   2. 수신한 표현을 통해 클라이언트가 리소스 조작을 할 수 있어야 한다.(HTTP 메소드)
   3. 클라이언트에 반환되는 자기기술적(self-descriptive)메세지가 포함되어야 한다.
   4. 하이퍼미디어 : 클라이언트가 리소스에 엑세스한 후 하이퍼링크를 사용해 수행가능한 모든 작업을 찾을 수 있어야 한다.
5. 계층구조 : REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할수 있다.
6. 코드 온디멘드(선택사항) : 서버에서 실행가능한 코드를 전송, 클라이언트의 기능을 확장한다.

1,2,3,5 번은 HTTP프로토콜로 통신하는 웹 애플리케이션이면 모두 만족하는 사항이며, 6번은 선택사항이다. 그럼 문제가 되는 부분은 4번 통합인터페이스 인데 한번 보도록 하자.

• 정보가 표준 형식으로 전송되기 위한 통합 인터페이스
  1. 요청된 리소스가 식별가능**(URI)**하며 클라이언트에 전송된 표현과 분리
  2. 수신한 표현을 통해 클라이언트가 리소스 조작을 할 수 있어야 한다.(HTTP 메소드)
  3. 클라이언트에 반환되는 자기기술적(self-descriptive)메세지가 포함되어야 한다.
  4. 하이퍼미디어 : 클라이언트가 리소스에 엑세스한 후 하이퍼링크를 사용해 수행가능한 모든 작업을 찾을 수 있어야 한다.

4-1,4-2는 이미 설명한 사항이지만, 3번과 4번은 언급이 된적이 없고, 실제로도 잘 지켜지지 않는다고 한다. 3번과 4번을 만족시키기 위해 HATEOS라는것이 나왔다. 간단히 말하면 3번은 API응답에 API문서가 있어야 한다는 것이다. (자기 기술, 인터페이스 명세서 같은 느낌?) 4번은 API응답에 하이퍼링크를 포함해 다른 API도 확인이 가능해야 한다는 것이다.

HATEOS는 API응답 시 응답본문인 data와, 3,4번 내용인 links로 같이 응답한다. links에는 호출된 API 문서 주소와, 연관된 다른 API의 주소와 문서주소를 하이퍼링크의 형태로 제공한다!

포스팅을 통해 알게된점

References

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

REST API(RESTful API, 레스트풀 API)란 - 서버, 구현, 사용법

https://meetup.toast.com/posts/92

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

https://youtu.be/PmY3dWcCxXI