REST API 톺아보기

API?

• 애플리케이션 프로그래밍 인터페이스(Application Programming Interface)는 애플리케이션 소프트웨어를 구축하고 통합하는 정의 및 프로토콜 세트
• 때때로 정보 제공자와 정보 사용자 간의 계약으로 지칭되기도 하며 소비자에게 필요한 컨텐츠(호출)과 생산자에게 필요한 컨텐츠(응답)을 구성함
• 리소스 검색 방법 또는 리소스의 출처에 대한 지식 없이도 사용 가능

한마디로 말하자면, 소프트웨어와 소프트웨어 사이에서 정보를 요청하는 지정된 양식대로 요청하고 응답을 줄 수 있는 수단

 

REST의 정의

• 자원을 이름(자원의 표현)으로 구분해 해당 자원의 상태(정보)를 주고 받는 모든 것
  • 자원: 해당 소프트웨어가 관리하는 모든 것(문서, 사진 등)
  • 표현: 그 자원을 표현하기 위한 이름(DB 내 학생 정보가 자원이라면 students를 자원의 표현으로 정함)
  • 상태 전달: 데이터가 요청되는 시점에서의 자원의 상태를 전달, JSON이나 XML 형식으로 주고받는 것이 일반적
• 자원의 표현에 의한 상태 전달, 각 요청이 어떤 동작이나 정보를 위한 것인지를 요청의 모습 자체로 추론할 수 있음
• 어떤 자원에 대해 CRUD 연산을 수행하기 위해 URI로 GET, POST, DELETE, UPDATE 등의 방식을 사용하여 요청을 보내며, 요청을 위한 자원은 특정한 형태로 표현

 

왜 REST API를 사용하는가?

각 요청이 어떤 동작이나 정보를 위한 것인지를 요청의 모습 자체로 추론할 수 있기 때문에 다른 개발자와의 협업이 수월해진다.

 

REST의 구성 요소

자원(Resource) - URI

1. 모든 자원에는 고유한 ID가 존재하고, 이 자원은 Server에 존재
2. 자원을 구별하는 ID는 /students/:student_id 와 같은 HTTP URI
3. Client는 URI를 이용해 자원을 지정하고 해당 자원의 상태에 대한 조작을 서버에 요청

행위(Verb) - Method

1. HTTP 프로토콜의 Method를 사용
2. HTTP 프로토콜의 Method 중 REST API 통신을 위해 사용하는 Method는 다음의 4~5가지

Method	설명	Body 유무
GET	Read: 정보 요청	X
POST	Create: 정보 입력	O
PUT	Update: 정보 갱신(데이터 전체)	O
Delete	Delete: 정보 삭제(안전성 문제로 대부분의 서버에서 비활성화)	X
(PATCH)	Update: 정보 갱신(데이터 일부)	O

POST만으로 생성, 조회, 수정, 삭제가 모두 가능하지만, 누구나 요청의 의미를 쉽게 파악할 수 있도록, RESTful하게 사용하기 위해선 목적에 따라 구분해서 사용해야 함!

표현(Representation of Resource)

1. Client와 Server가 데이터를 주고받는 형태로 JSON, XML, TEXT, RSS 등이 있음
2. 사용 언어와 상관없이 사용 가능하고 인간과 기계 모두 읽을 수 있는 JSON이 가장 널리 사용됨

 

REST API의 장점을 살리기 위한 URI 설계 규칙

1. 리소스를 표현하기 위해 명사를 사용하라

REST URI가 가리키는 자원은 수행하는 행위가 아니라 수행되는 객체다.

Good

https://api.goodlifelab.kr/posts

Bad

https://api.goodlifelab.kr/write-post

 

2. URI 작성에 일관성을 갖춰라

1. 계층 관계 표현을 위해 /를 사용하라
2. 마지막 문자로 /를 사용하지 마라
3. _ 대신 - 을 사용하라
4. 일부 브라우저나 화면에서는 _ 가 가려질 수 있다.
5. 소문자를 사용하라
6. RFC 3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다.

Good

https://api.goodlifelab.kr/my-data/students/13

Bad

https://api.goodlifelab.kr/My_Data/students/13/

 

3. 파일 확장자를 사용하지 마라

URI에 직접 확장자가 붙게 되면 해당 리소스 URI가 응답으로 지원하는 확장자만큼 새로운 URI들이 생기게 된다. 또한 고유한 리소스를 나타내는 데 사용되는 URI에 확장자를 붙이게 되면 표현 방식만 다른 같은 리소스가 서로 다른 정보를 담고 있는 것처럼 보이게 된다.

URI에 파일 확장자를 명시하는 대신 Request Header의 Content-Type 태그로 받고자 하는 리소스의 타입을 명시할 수 있다.

Good

https://api.goodlifelab.kr/timestamp
+ Content-Type: application/json

Bad

https://api.goodlifelab.kr/timestamp.json

 

4. CRUD 함수명을 사용하지 마라

리소스에 대한 작업은 HTTP Method로 구분, 이용하도록 한다.

Good

https://api.goodlifelab.kr/posts
+ POST Method

Bad

https://api.goodlifelab.kr/posts/create

 

5. 필터를 위해 쿼리 파라미터를 사용해라

리소스에 대한 정렬, 필터링, 페이징은 신규 API를 생성하는 방법 대신 쿼리 파라미터를 활용하자.

Good

https://api.goodlifelab.kr/posts/search?author=jade
https://api.goodlifelab.kr/posts/search?author=jade&sort=date

Bad

https://api.goodlifelab.kr/posts/author/jade

 

느낀 점

내가 여태까지 만든 API는 하나도 RESTful하지 않았다! 하지 말라는 거 다 했다! 부끄럽다

다음 프로젝트부터는 RESTful한 API를 만들 거다.

http://myproject.dev/api/generate_badge?boj=ccoco

http://api.myproject.dev/boj-badge?handle=ccoco

 

References

RESTful API Design, Second Edition

 

REST란? REST API 와 RESTful API의 차이점?

REST Resource Naming Guide

[네트워크] REST API란? REST, RESTful이란?