[TIL]WEB/CS : RESTful API

은경·2022년 1월 14일

CS TIL web

[WEB/HTTP]

목록 보기

4/7

1. RESTful API란 ❓

RESTful API란 REST(Representational State Transfer) 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스이다.

HTTP 통신에서 어떤 자원에 대한 CRUD 요청을 Resource와 Method로 표현하여 특정한 형태로 전달하는 방식

2. REST(Representational State Transfer)

최근의 서버 프로그램은 다양한 클라이언트의 등장과 여러 브라우저와 스마트폰과 같은 모바일 디바이스에서도 통신을 할 수 있어야 하고, 이러한 멀티 플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처를 세우고 이용하는 방법을 모색한 결과 REST에 관심을 가지게 되었다 .

REST의 정의
- 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다. 즉, 자원(resource)의 표현(representation) 에 의한 상태 전달을 의미 -> 자원 : DB의 음식정보 / 자원의 표현 : 'foods'
- JSON, XML를 통해 데이터를 주고받음.
- 이러한 REST 기반의 API를 웹으로 구현한 것이 RESTful API이다.
- REST는 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일.
REST의 개념
- HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미
REST의 구성요소
- Resource : 자원
  웹 사이트의 이미지, 텍스트, DB 내용 등의 모든 자원(Resource)에 고유한 ID인 HTTP URI를 부여한다.
  
  📌
  URL : Uniform Resource Locator 인터넷 상 자원(파일)의 위치
  URI : Uniform Resource Identifier 자원을 식별하기 위한 문자열의 구성
  URI는 URL을 포함하고 더 포괄적인 범위
- Method : 행위
  HTTP 프로토콜의 Method를 사용
  서버에 요청을 보내기 위한 방식, CRUD 연산 중에서 적절한 Method를 사용하여 서버에 요청을 보내야 함.
```
<CRUD Operation> 
Create : 생성(POST)
Read : 조회(GET)
Update : 수정(PUT, PATCH)
Delete : 삭제(DELETE)
HEAD: header 정보 조회(HEAD)
```
- Representation of Resource
  클라이언트와 서버가 데이터를 주고받는 형태로 JSON, XML, text, rss 등이 있다. Key, Value를 활용하는 Json을 주로 사용.
REST의 장점
- HTTP 프로토콜의 인프라를 그대로 사용, 별도의 인프라를 구출할 필요없음.
- HTTP 프로토콜의 표준을 최대한 활용하며, 이를 따르는 모든 플랫폼에서 사용 가능
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장.
- REST API 메시지가 의도하는 바를 명확하게 나타내서 쉽게 파악가능.
- 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- 서버와 클라이언트의 역할을 명확하게 분리한다.
REST의 단점
- 표준이 없다.
- 사용할 수 있는 메소드가 4개로 한정.
- HTTP Method 형태가 제한적.
- 구형 브라우저는 지원이 잘 되지 않음.
- PUT, DELETE를 사용하지 못하는 점
- pushState를 지원하지 않는 점

REST의 특징
1. Client-Server Architecture (서버-클라이언트 구조)
  - 자원이 있는 쪽 = 서버 / 자원을 요청하는 쪽 = Client
  - Server: API 제공, 비즈니스 로직 처리, 저장
  - Client: 사용자 인증, context(세션, 로그인 정보) 등 직접 관리
  - 역할 구분으로 서로 간 의존성을 줄임.
2. Stateless(무상태)
  - HTTP 프로토콜은 Stateless Protocol이므로 REST 역시 무상태성을 가짐.
  - 이전 요청이 다음 요청에 연관되지 않아야함.
  - Client의 context(세션, 쿠키 등)를 Server에 저장하지 않는다.
  - 그러므로 구현이 단순하고 서비스의 자유도가 높다
  - 서버의 처리 방식에 일관성 부여, 서버 부담은 줄어듬.
3. Cacheable(캐시 처리 가능)
  - 웹 표준 HTTP 프로토콜을 그대로 사용 -> 웹에서 사용하는 기존의 인프라를 그대로 활용할 수 있다.
  - HTTP의 특징 중 하나인 캐싱 기능을 적용할 수 있다.
  - HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현 가능.
  - 캐시를 이용해 대량의 요청을 효율적으로 처리 가능.
  - 캐시 사용시 REST Server 트랜잭션이 발생하지 않기 때문에 전체 응답시간, 성능, 서버의 자원 이용률을 향상 가능.
4. Layered System(계층화)
  - Client는 REST API Server만 호출한다.
  - REST Server는 다중 계층으로 구성될 수 있음.
  - API Server는 순수 비즈니스 로직을 수행, 계층을 추가하여 보안, 로드밸런싱, 암호화, 사용자 인증 등을 추가하여 구조변경 가능.
  - 로드밸런싱, 공유 캐시 등을 통해 확장성과 보안성 향상.
  - PROXY, Gateway 같은 네트워크 기반의 중간 매체 사용 가능.
5. Self-Descriptiveness(자체 표현)
  - REST API는 요청 메세지만 보고도 이를 쉽게 이해할 수 있는 자체표현 구조로 되어있음.
  - JSON 형태의 REST 메세지는 요청 의도 등을 내포하고 있음.
6. Uniform Interface(일관된 인터페이스)
  - URI로 지정한 Resource에 대한 요청을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일.
  - HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
  - 특정 언어나 기술에 종속되지 않는다.
  - Loosely Coupling(느슨한 결함) 형태를 가짐.

REST의 규칙

📌
 - URI는 명사를 사용.
 - URI는 소문자로만 구성.
 - 슬래시(/)로 계층 관계를 표현.
 - URI의 마지막에는 슬래시를 붙이지 않는다.
 - 가독성이 떨어지는 경우 하이픈(-)을 사용.

3. REST API 디자인 규칙

URI는 정보의 자원을 표현해야 한다.
자원에 대한 행위는 HTTP 메소드로 표현한다.

URI는 정보의 자원을 표현해야 한다.
- 자원은 동사X 명사O / 대문자X 소문자O
- 도큐먼트 이름은 단수 명사 사용. 도큐먼트 : 객체 인스턴스나 데이터베이스 레코드와 유사한 개념
- 컬렉션 이름은 복수 명사 사용. 컬렉션 : 서버에서 관리하는 디렉터리라는 리소스
- 스토어 이름은 복수 명사 사용. 스토어 : 클라이언트에서 관리하는 리소스 저장소
자원에 대한 행위는 HTTP 메소드로 표현한다.
- URI에 HTTP 메소드가 들어가면 안된다.
- URI에 행위에 대한 동사 표현이 들어가면 안됨.
- 경로 중 변하는 부분은 유니크한 값으로 대체.

GET/members/insert/2 (x) # GET 메서드는 리소스 생성에 맞지 않다.
POST/members/2       (o)

3-1. 설계 시 주의할 점

슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
URI 마지막 문자로 슬래시(/)를 포함하지 않는다. (혼동을 주지 않도록 분명한 URI를 만들어야 함)
하이픈(-)은 URI 가독성을 높이는데 사용
밑줄(_)은 URI에 사용하지 않는다.(가독성)
URI 경로에는 소문자가 적합.
- 대소문자에 따라 다른 리소스로 인식한다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정되어 있음.
파일 확장자는 URI에 포함시키지 않는다.(Accept header를 사용)

http ://restapi.example.com/members/soccer/345/photo.jpg (X)
GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg (O)

3-2. 리소스 간의 관계 표현법

REST 리소스 간에 연관 관계가 있는 경우

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

<서브 리소스에 명시적으로 표현하는 방법>
GET : /users/{userid}/likes/devices (사용자가 좋아하는 디바이스 목록)

3-3. 자원을 표현하는 Collection과 Document

도큐먼트 : 문서, 한 객체
컬렉션 : 문서들의 집합, 객체들의 집합

http:// restapi.example.com/sports/soccer/players/13

sports, players 컬렉션과
soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 구성됨.
컬렉션은 복수로 사용, 도큐먼트는 단수로 사용.

4. HTTP 응답 상태 코드

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 함.
응답의 상태 코드로도 많은 정보를 전달 하기 때문에 값을 명확히 돌려주는 것이 중요하다.
HTTP Status Code 정리 자료 [MDN]

5. REST API의 목적

다시 돌아와서, RESTful API란❓
-> RESTful은 일반적으로 REST라는 아키텍처를 구현하는 웹 서비스를 나타내는 용어.

‘REST API’를 제공하는 웹 서비스를 ‘RESTful’하다고 할 수 있다.
RESTful은 REST를 REST답게 쓰기 위한 방법
REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.

사용 목적

이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것
RESTful한 API는 성능 향상과는 관련없이, 일관적인 컨벤션을 통한 API의 이해도와 호환성을 높이는 것이 주 목적.
성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없다.

참고 자료(References)

그런 REST API로 괜찮은가
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://mangkyu.tistory.com/46
https://meetup.toast.com/posts/92
https://sookiwi.com/posts/tech/2018/11/11/Is-it-okay-with-such-REST-APIs/

은경

Python 서버 개발자

이전 포스트

[TIL] WEB/HTTP : 브라우저 동작원리

다음 포스트