지난번 프로젝트를 진행하면서 코치님께 RESTful한 API 설계에 대해서 조언을 들었었다.
나는 그동안 나름 RESTful하게 API를 설계하고 있다고 생각했는데 전혀 아니었다... ㅎㅎ
다음 프로젝트 때는 실수하지 않기 위해서 오늘은 RESTful API에 대해서 공부해보았다!!
RESTful API
RESTful API(Representational State Transfer API) 월드 와이드 웹과 같은 분산 하이퍼 미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식으로 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반에 대한 패턴을 말한다.
REST의 구성
- 자원(Resource) - URI
- 행위(Verb) - HTTP method
- 표현(Representations)
REST의 특징
- Uniform (유니폼 인터페이스)
- Stateless(무상태성)
- Cacheable(캐시 가능)
- Self-descriptiveness(자체 표현 구조)
- Client-Server 구조
- 계층형 구조
REST API 디자인 가이드
- URI는 정보의 자원을 표현해야 한다.
- 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
- 이 외의 주의할 점
- 슬래시 구분자는 계층관계를 나타내는 데 사용
- URI 마지막 문자로 슬래시를 포함하지 않는다.
- 하이픈(-)은 가독성을 위해 사용가능하나 언더바(_)는 사용하지 않는다.
- URI 경로는 소문자로 작성한다.
- 파일 확장자는 URI에 포함시키지 않는다.
- 리소스 간의 관계를 표현하는 방법 REST 리소스 간에 연관 관계가 있을 경우 아래와 같이 사용한다.
/리소스명/리소스 ID/관계가 있는 다른 리소스명관계명이 애매하거나 구체적 표현이 필요할 때는 서브리소스에 명시적으로 표현할 수 있다.
- 자원을 표현하는 Collection과 Document
http: // restapi.example.com/fruits/apple위 URI는 fruits라는 collection과 apple이라는 document로 표현되고 있다. collection은 document의 집합이고 collection은 복수로 나타내야 한다.
HTTP 응답 상태 코드
🙆♀️ 성공시? 2xx!
| 상태코드 | |
|---|---|
| 200 | 클라이언트의 요청을 정상적으로 수행함 |
| 201 | 클라이언트가 어떠한 리소스 생성을 요처으 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업시) |
🙅♀️ 실패시? 4xx!
| 상태코드 | |
|---|---|
| 400 | Bad Request 클라이언트의 요청이 부적절할 경우 사용하는 응답 코드로 파라이터의 위치(path, query, body), 사용자 입력 값, 에러 이유 등을 반드시 알린다. |
| 401 | 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 |
| 404 | Not Found |
| 405 | Method Not Allowed 클라이언트가 요청한 리소스에서는 사용불가능한 Method를 이용했을 경우 사용하는 응답 코드 |
👉 기타 등등
| 상태코드 | |
|---|---|
| 301 | 클라이언트가 요청한 리소스에 대한 URI가 변경되었을 때 사용하는 응답코드로 응답시 location header에 변경된 URI를 적어줘야 함 |
| 500 | 서버에 문제가 있을 경우 사용하는 응답코드로 사용자에게 나타내서는 안된다. |
RESTful API의 장점 & 단점
장점 👍
- Open API를 제공하기 쉽다.
- 멀티플랫폼 지원 및 연동이 용이하다.
- 원하는 타입으로 데이터를 주고 받을 수 있다.
- 기존 웹 인프라(HTTP)를 그대로 사용할 수 있다.
단점 👎
- 사용할 수 있는 메소드가 4가지밖에 없다.
- 분산환경에는 부적합하다
- HTTP 통신 모델에 대해서만 지원한다.
Ref
꾸준히 열심히!