REST API , RESTful

김석·2023년 5월 29일

REST API Restful

Network

목록 보기

7/9

1. REST

Representational State Transfer: 자원의 표현으로 상태를 전달하는 것.
네트워크 아키텍처 스타일 = 네트워크 자원을 정의하고 처리하는 방법 전반.
HTTP의 장점을 최대한 활용할 수 있는 아키텍처.
자원을 정의하고 자원에 대한 주소를 지정하는 방법론.
확장성과 재사용성을 높여 유지보수 및 운용을 편리하게 함.
이해하기 쉽고 사용하기 쉬운 API를 제작하려는 목적.

REST는 HTTP를 잘 활용하기 위한 원칙.
REST API는 이 원칙을 잘 준수하여 만든 API.

REST한 API를 설계 중심 규칙

URI는 자원을 표현하는데에 집중.
자원의 상태(행위)는 HTTP Method로 정의.

URI로 자원을 표현 & 자원에 대한 행위는 HTTP Method로 표현.

GET /deleteUserInfo/id?=3 vs DELETE /users/3

두 요청 모두 특정 user의 정보를 삭제하는 API이지만, 1번 API는 RESTful하지 못함.
이후 API의 이해도를 떨어뜨리며, 확장성도 없다.
REST API를 사용한다고 해서 성능이 향상되지는 않지만, API의 이해도 및 호환성을 높이기 위해 REST API를 사용하는 것이 권장됨.

2. REST 특징

1. Uniform(단일 인터페이스)

Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 뜻함.

2. Stateless(무상태성)

작업을 위한 상태 정보를 따로 저장하고 관리하지 않음.
세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청을 단순 처리만 하면 됨.
이 때문에 서비스의 자유도가 높아지고, 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해짐.

3. Cacheable(캐시 가능)

REST는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에 기존 인프라를 기대로 활용할 수 있음.
따라서 HTTP가 가진 캐싱 기능이 적용 가능.
HTTP 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용해 캐싱 구현 가능.

4. Self-descriptiveness(자체 표현 구조)

REST API만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조임.

5. Client-Server 구조

REST 서버는 API를 제공함.
클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 관리함.
각각의 역할이 확실히 구분되는 구조이기 때문에, 각 영역에서 개발해야 할 내용이 명확해지고, 의존성이 줄어듦.

6. 계층형 구조

다중 계층으로 구성될 수 있음.
따라서 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있음.
Proxy, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있음.

3. REST API 설계 가이드

1. 동사보다 명사 사용, 대문자보다 소문자 사용

GET http://seok0301.com/Running
->
http://seok0301.com/run

2. URI에 HTTP Method가 들어가면 안 됨

GET /books/delete/1
->
DELETE /books/1

3. URI에 행위를 포함하면 안 됨

DELETE http://seok0301.com/delete-post/1
->
DELETE http://seok0301.com/run

4. 경로 부분 중 변하는 부분은 유일한 값으로 대체
id는 하나의 특정 resource를 나타내는 고유값을 의미

student를 생성하는 URI가 POST /students 라면,
id = 10 인 student를 삭제하는 URI는 DELETE /students/10

5. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현.

6. 마지막에 슬래시 (/)를 포함하지 않음

POST http://seok0301.com/test
->
POST http://seok0301.com/test

7. 언더바(_) 대신 하이폰(-)을 사용

GET http://seok0301.com/test_blog
->
GET http://seok0301.com/test-blog

8. 파일 확장자는 URI에 포함하지 않고, 대신 Accept header를 사용

GET http://seok0301.com/photo.jpg
->
GET http://seok0301.com/photo

9. 리소스 간에 연관 관계가 있는 경우 표현 형식.
/리소스명/리소스 ID/관계가 있는 다른 리소스명

GET /books/{bookid}/viewers (일반적으로 소유 ‘has’의 관계를 표현할 때)

10. 자원 표현 방식

도큐먼트
- 1개의 객체를 나타냄.
- database의 record와 유사한 개념.
- 단수 명사로 표현.
- 컬렉션 뒤에 /를 통해 구분됨.

컬렉션
- 자원(도큐먼트)의 집합.
- 복수 명사로 표현.
- 단일 리소스가 아니라 다량의 리소스(자원 리스트)가 필요할 때 호출.

GET http://seok0301.com/sports
sports라는 컬렉션 요청

GET http://seok0301.com/sports/soccer
soccer라는 도큐먼트 요청

GET http://seok0301.com/sports/soccer/players
players라는 컬렉션 요청

GET http://seok0301.com/sports/soccer/players/13
13번 선수라는 도큐먼트 요청