RESTful API

1. RESTful API란?

1) API란?

프론트엔드와 백엔드를 연결해주는 인터페이스.

프론트엔드가 손님이고 백엔드가 은행이면 api는 은행 창구이다.

프론트엔드는 api로 요청을 보내고, 백엔드는 api로 받은 요청을 실행해서 프론트엔드에게 응답한다.

2) REST란(REpresentational State Transfer)?

REST는 HTTP 요청을 표현하는 방법이다.

HTTP 요청은 근본적으로 다음과 같다.
1) 특정 리소스에
2) 어떤 작업을 해달라.

REST 방법에서는
1) 원하는 것이 무슨 리소스인지 URI로 표현한다.
2) 어떤 작업을 해달라는 건지 HTTP Method로 표현한다.

- URI
URI는 리소스의 고유한 이름(=주소)이다.
REST는 웹에 필요한 모든 리소스(이미지, 영상, 데이터 등)에 고유한 URI를 붙여 리소스를 특정한다.

REST는 URI를 효과적으로 설계하는 규칙을 제시한다.   

"REST = URI를 잘 짓는 방법"이라고 해도 될 정도이다.
이 규칙에 따라 URI를 만들면 URI만으로 리소스 내용을 직관적으로 표현할 수 있다.(self-descriptiveness)

- HTTP method
REST는 HTTP 메서드 GET, POST, PUT, PATCH, DELETE만으로 CRUD를 표현한다.

따라서 원하는 작업에 따라 적절한 HTTP 메서드를 사용해야 한다.

3) RESTful API란?

REST 규칙이 잘 적용된 API.
잘 지은 URI와 적절한 Http Method를 받는 API.

REST는 제안이지 규약이 아니기 때문에 REST를 안 지킨다고 웹이 안 돌아가지는 않는다.
하지만 REST 원칙을 따르면 좀 더 가독성 있고 논리적으로 요청을 주고받을 수 있다.

예를 들어 REST 원칙을 사용하여 작성한 요청 메시지를 보면,

GET /users/1/profile-photo

1번 유저의 프로필 사진을 가져오라는 요청임을 쉽게 파악할 수 있다.

2. RESTful API 설계 규칙

1. URI를 명확하게 작성해야 한다.

GET /user/1 (x)
GET /users/1 (o)

여러 명의 유저 중 1번 유저를 가져오라는 뜻이므로
user보다 users가 적절하다.

2. URI에 동사를 포함하면 안 된다.
리소스에 대한 행위는 HTTP method로만 표현해야 한다.

GET delete/user/1 (x)
DELETE /users/1   (o)

1번 유저를 삭제하고 싶은 것이라면
HTTP 메서드를 DELETE으로 지정하는 것으로 충분하다.

3. 리소스 사이에 관계가 있는 경우 /로 계층을 표현한다.
/리소스/고유 ID/관계 있는 리소스

GET /users/1/profile

4. 파일 확장자를 URI에 포함시키면 안된다

GET /users/1/profile-photo.jpg (x)
GET /users/1/profile-photo     (o)

5. URI 마지막 문자로 /를 넣으면 안된다.

GET /users/1/ (x)
GET /users/1  (o)

6. URI가 길어지는 경우 하이픈을 사용한다.
언더바는 가독성이 좋지 않으므로 사용하지 않는 것이 원칙이다.

GET /users/1/profile_photo (x)
GET /users/1/profile-photo (o)

7. URI 경로에 대문자를 쓰면 안 된다.

GET /users/1/Profile (x)
GET /users/1/profile (o)

 

3. Query parameter & Path parameter

Query parameter

리소스를 filtering, sorting, searching할 때 사용한다.
URI에 ?key=value형태로 넣는다.

# price가 3000인 제품을 요청
GET /products?price=3000

# price가 3000이고 이름이 apple인 제품을 요청
GET /products?price=3000&name=apple

# id 순으로 제품을 정렬해서 가져오라는 요청
GET /products?ordering=id

# 제품을 100개만 가져오라는 요청
GET /products?offset=0&limit=100

# sue라는 유저를 찾아서 가져오라는 요청
GET /users?search=sue

Path parameter

리소스의 상세한 정보를 요청할 때 사용한다.
보통 URI에 리소스 아이디를 넣는 식으로 사용한다.

# 1번 제품의 상세 정보를 가져오라는 요청
GET /products/1

 

4. HTTP Method

1) GET(CRUD의 Read 역할)

리소스를 가져오라는 요청이다.

서버에게 전달할 내용(요청할 상품의 아이디, 필터링 기준 등)은 URI에 실어 보낸다.

 

GET 요청은 캐시와 브라우저 히스토리에 남으므로

보안상 민감한 정보는 절대 GET으로 보내면 안 된다.

2) POST(CRUD의 Create, Update 역할)

새로운 리소스를 생성하거나 기존 리소스를 업데이트하라는 요청이다. 

 

서버에게 전달하고 싶은 내용은 HTTP request의 body에 실어 보낸다.

GET 요청과 달리 보내는 데이터의 길이 제한이 없으며

캐시와 브라우저 히스토리에 남지 않는다.

 

해당 요청 URI의 자식이 되는 리소스를 생성할 때 사용한다.

예) 유저를 만들 때 => POST /users

 

같은 POST 요청을 여러 번 보내면 매번 결과가 달라진다.

예) 유저를 만들라는 요청 POST /users를 10번 보내면 유저가 10명 생성됨

3) PUT(CRUD의 Create, Update 역할)

POST와 마찬가지로 리소스를 생성하거나 업데이트하라는 요청이다.

 

해당 요청 URI의 리소스를 생성하거나 수정할 때 사용한다.

예) 10번 유저를 만들 때 => PUT /users/10

 

PUT은 POST와 달리 같은 요청을 여러 번 보내도 결과가 달라지지 않는다.

예) 유저를 만들라는 요청 PUT /users/10을 10번 보내면 유저를 1명 생성한 후 계속 같은 유저를 업데이트함

4) PATCH(CRUD의 Update 역할)

이미 존재하는 리소스의 일부만 업데이트하라는 요청이다.

PUT과 마찬가지로 해당 요청 URI의 리소스를 수정할 때 사용한다.

PUT은 리소스 전체를 갈아끼울 때 사용하고, 

PATCH는 리소스의 일부만 업데이트할 때 사용한다.

 

예) 10번 유저의 모든 정보를 바꾸라는 요청 PUT /users/10

예) 10번 유저의 전화번호만 바꾸라는 요청 PATCH /users/10

5) DELETE(CRUD의 Delete 역할)

리소스를 삭제하라는 요청이다.

put은 정보를 통째로 갈아끼울 때 사용
patch는 정보의 일부만 업데이트할 때 사용

 

 

참고
RESTful API란?

HTTP Methods GET vs POST

Stack Overflow - What is the difference between POST and PUT in HTTP

gabia - RESTful API 설계 가이드