REST API 개념, 특징, 및 설계 규칙

개념

• REST API란 ?
  • REpresentational State Transfer (자원을 이름으로 구분하여 해당 자원의 정보를 주고 받는 모든 것을 의미)
  • REST 아키텍쳐 스타일을 따르는 API
• 그렇다면 REST란?
  • 분산 하이퍼 미디어 시스템(웹)을 위한 아키텍쳐 스타일
• 그렇다면 아키텍쳐 스타일이란?
  • 제약 조건의 집합 

즉, REST API란

분산 하이퍼 미디어 시스템(웹)에서 자원을 이름으로 구분하여 정보를 주고받는 제약 조건들을 적용한 API 

---

REST API가 필요한 이유?

• 다양한 클라이언트의 등장
• 에플리케이션 분리 및 통합

---

REST API 특징

 

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

• 서로간의 의존성이 줄어든다.

2. Stateless (무상태)

• Client의 context를 Server에 저장하지 않는다.
• Server는 각각의 요청을 완전히 별개의 것으로 인식하고 처리한다.

3. Cacheable (캐시처리기능)

4. Layered system (계층화)

• Client는 REST API Server만 호출한다.
• 다중 계층으로 구성될 수 있다.

5. Uniform interface (인터페이스 일관성) - 만족시키기 힘들다

• URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.

 

위의 특징을 모두 만족시켜야 만이 API가 RESTful하다고 말 할 수 있다. REST API의 특징을 살펴보면 HTTP 규칙만 잘 따라도 Client-server, Stateless, Cache, Layered system은 조건에 부합한다. 만족시키기 힘든 특징은 Uniform interface인데 그것에 대해 자세히 알아보자.

 

uniform interface

• identification of resources  (리소스가 URI를 식별될 수 있으면 된다)
• manipulation of resources through reporesentations (PUT, DELETE, POST, GET ...)
• self-descriptive messages (메세지는 스스로를 설명해야 한다.)

 

첫번째와 두번째 특징을 만족시키는 REST 설계 규칙-1

세번째 특징을 만족시키는 REST 설계규칙-2를 살펴보자.

 

 

---

 

REST API 설계 규칙 - 1

identification of resources URI는 정보의 자원을 표현해야 한다
manipulation of resources through reporesentations 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다

 

대문자보다는 소문자 사용 (카멜케이스보다 하이픈 사용)

 

BAD

http://restapi.example.com/Users/postComments

 

GOOD

http://restapi.example.com/users/post-comments

---

url는 명사를 사용

 

BAD

/addNewEmployee
/updateEmployee
/deleteEmployee
/deleteAllEmployees
/promoteEmployee
/promoteAllEmployees

 

GOOD

HTTP 메소드(GET, POST, DELETE, PUT)로 동사 표현하기

 

GET (조회)

 

GET /companies # companies의 모든 목록을 가져온다.
GET /companies/34 # company의 34의 상세 내용을 가져온다
GET /companies/3/employees # company 3에 속하는 employees 전체 목록을 가져온다
GET /companies/3/employees/45 # company3에 속하는 employees 45의 상세 내용을 가져온다

 

POST(등록)

멱등성(여러번 실행되어도 바뀌지 않는 성질)을 갖지 않는다. (여러번의 request는 각각 다른 영향을 미친다.)

 

POST /companies # 새로운 company를 생성하고, 생성된 company의 상세 내용을 리턴한다.
POST /companies/3/employees  #company 3에 새로운 employee를 생성한다.

 

PUT(수정)

멱등성(여러번 실행되어도 바뀌지 않는 성질)을 갖는다.

 

PUT /companies/3/employees/john # company 3에 속하는 employees collection에 john이라는 resource를 업데이트하거나 생성하도록 서버에 요청한다.

 

DELETE(삭제)

 

DELETE /companies/34 # company 34를 삭제한다.
DELETE /companies/3/employees/45 # company 3에 속하는 employee 45를 삭제한다.
DELETE /companies/3/employees/john/ # company 3에 속하는 employees collection에서 john이라는 resource를 삭제하도록 서버에 요청한다.

 

BAD

http://restapi.example.com/users/add-post
http://restapi.example.com/users/delete-all

 

GOOD

http://restapi.example.com/users/post-comments

---

언더바 대신 하이픈을 사용 (밑줄은 사용하지 않는다)

 

BAD

http://restapi.example.com/users/post_comments

 

GOOD

http://restapi.example.com/users/post-comments

---

마지막에 슬래시는 포함하지 않는다.

슬래시는 계층구조를 구분할 때 사용

 

BAD

http://restapi.example.com/users/post-comments/

 

GOOD

http://restapi.example.com/users/post-comments

---

파일 확장자는 URI에 포함되어서는 안 된다.

 

BAD

http://api.college.com/students/3248234/courses/2005/fall.json

 

GOOD

http://api.college.com/students/3248234/courses/2005/fall

 

---

REST API 설계 규칙 - 2

uniform interface의 마지막 규칙인 self-descriptive messages (메세지는 스스로를 설명해야 한다) 에 대한 규칙을 알아보자.

 

Header에 정보 담기 

목적지 명시하기

 

BAD

GET / HTTP/1.1

 

GOOD

GET / HTTP/1.1 
Host : www.example.org # 목적지를 추가하면 self-descriptive 하다.

 

JSON 명세서 명시

 

BAD

HTTP/1.1 OK
[{"op": "remove", "path": "/a/b/c"}]

 

GOOD

HTTP/1.1 OK
Content-Type: application/json-patch+json
[{"op": "remove", "path": "/a/b/c"}]

 

 

 

 

Reference

https://www.youtube.com/watch?v=RP_f5dMoHFc&ab_channel=naverd2

 

https://dzone.com/articles/7-rules-for-rest-api-uri-design-1

https://wayhome25.github.io/etc/2017/11/26/restful-api-designing-guidelines/

https://blog.restcase.com/5-basic-rest-api-design-guidelines/

https://devuna.tistory.com/79