[RESTful API] RESTful API란 무엇인가?

개요

개인 프로젝트에서 API 설계를 하는 도중, 내가 지금 RESTful 한 API를 제대로 설계하고 있는 것인지 의문이 들어 제대로 된 RESTful API란 무엇인지 찾아보게 되었다.

 

---

REST란 무엇인가?

Representational State Transfer(REST)

API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처이다. REST는 처음에 인터넷과 같은 복잡한 네트워크에서 통신을 관리하기 위한 지침으로 만들어졌으며, 이를 사용하여 대규모의 고성능 통신을 안정적으로 지원할 수 있다. 쉽게 구현하고 수정할 수 있어 모든 API 시스템을 파악하고 여러 플랫폼에서 사용할 수 있다.

 

---

REST의 특징

1. Uniform Interface

• 균일한 인터페이스는 URI로 지정한 리소스에 대한 조작을 통일하고 한정적인 인터페이스로 수행하는 아키텍쳐 스타일이다.형식이 지정된 리소스를 REST에서 representation 이라고 부른다. 이 형식은 서버 애플리케이션에 있는 리소스의 내부 표현과 다를 수 있다. 예를 들어, 서버는 데이터를 텍스트로 저장하되, HTML 표현 형식으로 전송할 수 있다.

2. Stateless

• REST는 무상태 성격을 갖고 있다. 다시 말해, 작업을 위한 상태 정보를 따로 저장하고 관리하지 않는다.
• Session 정보나 cookie 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 단순하게 요청만 처리하면 된다. 때문에 서비스의 자유도가 높아지고, 서버에서 불필요한 정보를 관리하지 않아서 구현이 단순해진다.

 3. Cachability

• REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용 가능하다는 점이다.
• 따라서, HTTP가 가진 캐싱 가능을 적용 가능하다 (HTTP 프로토콜 표준에서 사용하는 Last-Modified 나 E-Tag를 이용).

4. Code on demand (or Self-descriptiveness) (optional)

• REST의 또 다른 큰 특징 중 하나는 API 메시지만 보고도 내용을 쉽게 이해할 수 있는 "자체 표현 구조"로 되어 있다는 것이다.

5. Client-Server 구조

• 서버는 API 제공, 클라이언트는 사용자 인증이나 콘텍스트 (세션, 로그인 정보) 등을 직접 관리하는 구조로 역할이 확실하게 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간에 의존성이 줄어들게 된다.

6. Layered System

• REST 서버는 다중 계층으로 구성될 수 있으며, 보안, load balancing, 암호화 계층을 추가해 유연한 구조를 가질 수 있고, proxy, gateway 같은 네트워크 기반의 중간매체를 사용할 수 있다.

 

---

REST API 디자인 가이드

REST API 설계 시, 가장 중요한 2가지

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP method (GET, POST, PUT, DELETE, ...)로 표현한다.

 

규칙

URI는 정보의 자원을 표현해야 하며 (리소스명은 동사보다 명사로), 자원에 대한 행위는 HTTP method를 사용해야 한다.

POST /user/delete/1

위의 방식 보다는

DELETE /user/1

이 방식이 더 REST한 URI이다.

 

URI 설계 시 주의점

1. 슬래시 구분자 (/) 는 계층 관계를 나타내는 데 사용한다.

<http://example.com/developer/backend>
<http://example.com/drink/alcohol/soju>

 

2. URI 마지막에는 (/) 를 포함하지 않는다.

/foo/bar/ (X)
/foo/bar  (O)

 

3. 하이픈(-)은 가독성을 위하여, underscore(_) 는 URI에 사용하지 않는다.

 

4. 파일 확장자는 URI에 포함시키지 않는다.

/foo/bar/index.html (X)
/foo/bar/index 		(O)

 

5. URI 경로에는 소문자가 적합하다. 대소문자에 따라 다른 리소스로 인식하기 때문에, URI 경로에 대문자 사용은 피해야 한다.

 

6. 파일 확장자는 URI에 포함시키지 않는다.

/foo/bar/index.html	(X)

• REST API는 message body 내용의 포멧을 나타내기 위한 파일 확장자를 URI에 담지 않는다. 대신에, HTTP 헤더에 그 정보를 나타낸다.

 

리소스 간의 관계 표현

REST 리소스 간에는 연관 관계가 있을 수 있고, 이 경우에는 다음과 같이 표현한다.

/리소스명/리소스 ID/관계가 있는 다른 리소스명
GET : /users/{userid}/images (일반적으로 소유 ‘has’의 관계를 표현할 때)

 

만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다. 예를 들어 사용자가 ‘좋아하는’ 사진 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있다.

GET : /users/{userid}/likes/images

 

---

RESTful API 인증 방법

HTTP 인증

1. 기본 인증 - 클라이언트는 요청 헤더에 사용자 이름과 암호를 넣어 전송한다. 안전한 전송을 위해 이 페어를 64자의 세트로 변환하는 인코딩 기술인 base64로 인코딩한다.

 

2. 전달자 인증 - 전달자(bearer) 인증이라는 용어는 토큰 전달자에 대한 액세스 제어를 제공하는 프로세스를 나타낸다. 일반적으로 전달자 토큰은 서버가 로그인 요청에 대한 응답으로 생성하는 암호화된 문자열이다. 클라이언트는 리소스에 액세스하기 위해 요청 헤더에 토큰을 넣어 전송한다.

 

API Key

서버는 고유하게 생성된 값을 최초 클라이언트에 할당한다. 클라이언트는 리소스에 액세스하려고 할 때마다 고유한 API 키를 사용하여 본인을 검증한다. 하지만, API 키의 경우 클라이언트가 이 키를 전송해야 해서 네트워크 도난에 취약하다.

 

OAuthReference

OAuth는 모든 시스템에 대해 매우 안전한 로그인 액세스를 보장하기 위해 암호와 토큰을 결합한다. 서버는 먼저 암호를 요청한 다음 권한 부여 프로세스를 완료하기 위해 추가 토큰을 요청하고, 특정 범위와 수명으로 언제든지 토큰을 확인할 수 있다.

 

---

Reference

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

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

 

---