REST API

1. REST API

1. 개요

REST API는 REpresentational State Transfer의 줄임말로 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다. 이는 로이 필딩이 자신의 박사 학위 논문에서 소개하면서 알려졌다.

1. 구성

• 자원(Resource) - URI
• 행위(Verb) - HTTP method
• 표현(Representations)

2. 특징

1. Uniform Interface

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

2. Stateless

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

3. Cacheable

REST는 HTTP라는 웹 표준을 그대로 사용하기 때문에 웹에서 사용하는 인프라를 활용할 수 있다. 즉 HTTP의 캐싱 기능이 적용된다. Last-Modified나 E-Tag를 이용하면 캐싱 구현이 가능하다.

4. Self-descriptive

API 응답 결과만 보고도 이해할 수 있는 자체 표현 구조로 되어 있다.

5. Client-Server

REST 서버는 API를 제공하고, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보 등)을 직접 관리하는 구조로 각각의 역할이 확실히 구분되어 서로간 의존성이 줄어든다.

6. 계층형 구조

REST 서버는 다중 계층으로 구성될 수 있어 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상 유연성을 둘 수 있고, 프록시, 게이트웨이와 같은 네트워크 기반의 중간 매체를 사용할 수 있다.

3. 디자인 가이드

1. URI는 정보의 자원을 표현해야 한다.

// bad
GET /members/delete/1

// good
GET /members/1

URI는 자원의 표현에 중점을 두어야 한다. 따라서 행동은 HTTP Method로 표현한다.

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

// bad
POST /members/delete/1
POST /members/create/1

// good
DELETE /members/1
POST   /members

METHOD	역할	멱등성
GET	해당 리소스를 조회한다.	O
POST	해당 리소스를 생성한다	X
PUT	해당 리소스를 수정한다. 요청한 정보로 해당 리소스가 교체된다.	O
DELETE	해당 리소스를 삭제한다.	X
PATCH	해당 리소스를 수정한다. 요청한 정보만 해당 리소스에 반영한다.	X

⚠️ PUT 사용 시엔 해당 리소스에 대한 모든 정보를 함께 입력해주어야 한다. 그렇지 않으면 비어있는 필드 값이 null로 채워진다. PATCH는 비교적 최근에 만들어진 메소드로 아직 지원하지 않는 브라우저가 존재하므로 가능한 PUT을 활용하자.

3. URI 설계 시 주의할 점

1. 슬래시(/) 구분자는 계층 관계를 나타내는 데 사용한다.
2. URI 마지막 문자로 슬래시(/)는 포함하지 않는다.
3. 하이픈(-)은 URI 가독성을 높이는 데 사용한다.
4. 밑줄(_)은 URI에 사용하지 않는다.
5. URI는 소문자가 적합하다.
6. 파일 확장자는 URI에 포함하지 않는다.

4. 리소스 간 관계 표현 방법

// 리소스명/리소스 ID/관련된 다른 리소스
GET /users/{userId}/devices

// 특정 사용자가 좋아요를 누른 디바이스
GET /users/{userId}/likes/devices

5. Document, Collection

• Document
  • 단순히 문서 또는 하나의 객체
• Collection
  • Document의 집합

→ Document와 Collection 모두 리소스로 표현할 수 있으며 URI에 표현된다.

// sports라는 컬렉션과 soccer라는 document가 리소스로 표현
http://api/sports/soccer

// sports 컬렉션 내 soccer라는 document 안에 존재하는
// player 중 13번째 선수에 대한 리소스 요청
http://api/sports/soccer/players/13

4. 응답 상태 코드

상태 코드	설명
200(OK)	클라이언트의 요청을 정상적으로 수행
201(Created)	클라이언트가 리소스 생성을 요청했고 성공적으로 생성됨
204(No Content)	요청은 정상 처리되었으며 응답 바디에 데이터는 없음을 나타냄. 헤더에는 존재할 수 있음
301(Moved Permanently)	클라이언트가 요청한 리소스에 대한 URI가 변경되었음을 알림. Location 헤더에 변경된 URI를 포함하여 응답해야 함
400(Bad Request)	클라이언트의 요청이 부적절함
401(Unauthorized)	클라이언트가 인증되지 않은 상태로 보호된 리소스를 요청함
403(Forbidden)	클라이언트의 인증 상태와 관계 없이 응답하지 않고 싶은 리소스에 클라이언트가 접근함. 403보다는 400이나 404를 사용하는 편이 권장됨. 403 자체가 리소스가 존재한다는 뜻이기 때문
404(Not Found)	클라이언트가 요청한 리소스를 찾을 수 없음
405(Method Not Allowed)	요청한 메소드가 서버에서 사용할 수 없음
500(Internal Server Error)	서버 에러

2. API 성숙도 모델

Level 0: 1 URI, 1 HTTP method

API 서비스를 위해 단 1개의 endpoint를 제공한다. 그리고 전달되는 파라미터를 통해 하나의 endpoint로 여러 동작을 수행한다. 파라미터를 Body로 전달하기 때문에 항상 POST를 통해 통신한다.

Request

POST http://www.server.com/api/user

{
    "function": "getUserInfo",
    "id": ["1"]
}

Response

HTTP/1.1 200 OK
{
    "result": {
        "name": "jeidiiy",
        "id": "1"
    }
}

CRUD

CREATE - POST /www.server.com/api/user
READ   - POST /www.server.com/api/user
UPDATE - POST /www.server.com/api/user
DELETE - POST /www.server.com/api/user

Level 1: N URI, 2 HTTP method

REST API 구성 요소 중 Resource를 도입한 단계이다. Resource 별로 고유한 URI를 사용하여 식별한다.

Request

POST http://www.server.com/api/user/create

{
    "name": "jeidiiy"
}

Response

HTTP/1.1 200 OK
{
    "result": {
        "error": "This user is already existed."
    }
}

CRUD

CREATE - POST /www.server.com/api/user/create
READ   - GET /www.server.com/api/user/1
UPDATE - POST /www.server.com/api/user/update
DELETE - POST /www.server.com/api/user/delete/1

문제

1. 여전히 GET과 POST만 사용한다.
2. 에러가 발생했는데 200 OK 응답 코드를 내려준다.
3. 헤더에 Content-Type과 같은 정보가 없다.

Level 2: N URI, 4 HTTP method

GET, POST, PUT, DELETE 를 사용해서 CRUD를 나타내며 적절한 상태 코드도 함께 반환한다.

Request

POST http://www.server.com/api/users

{
    "name": "jeidiiy"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
{
    "result": {
        "name": "jeidiiy",
        "id": "1"
    }
}

CRUD

CREATE - POST    /www.server.com/api/users
READ   - GET     /www.server.com/api/users/1
UPDATE - PUT     /www.server.com/api/users
DELETE - DELETE  /www.server.com/api/users/1

특징

1. URI에 행동이 담겨 있지 않고 HTTP method를 통해 전달한다.
2. 201 Created와 같은 적절한 상태 코드를 반환한다. 또한 Content-Type과 같은 헤더 정보 또한 포함된다.
3. 현재 대부분의 서비스가 2단계 수준으로 운영된다.

Level 3: Hypermedia As Engine of Application State

이 단계에서는 API의 응답만으로 어떤 정보를 요청했는지 알 수 있도록 하며(Self-descriptive) 해당 정보와 관련된 정보들에 관련한 URI를 하이퍼텍스트로 제공한다. 이는 서버나 클라이언트가 변경되더라도 메시지는 언제나 스스로를 나타내므로 해석이 가능해야 한다는 뜻이다. 또한 링크는 언제나 동적으로 변경될 수 있기 때문에 하이퍼텍스트로 제공하여 링크가 변경되더라도 언제나 유연하게 사용할 수 있게 한다.

Request

GET http://www.server.com/users

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
    "data": [{
            "type": "user",
            "id": "1",
            "attributes": { "name": "Adam" },
            "link": { "self": "http://www.server.com/api/user/1" }
        }, {
            "type": "user",
            "id": "2",
            "attributes": { "name": "Ada" },
            "link": { "self": "http://www.server.com/api/user/2" }
        },
        // ...
    ]
}

특징

• Content-Type이 단순히 application/json이 아니라 더 구체적인 명세로 응답했다. 또한 data 안에 여러 하이퍼링크들이 JSON 형태로 포함되어 있다.
  • 이렇게 표현하는 방법에는 JSON API, HAL 등과 같은 명세들이 있다.

CRUD

CREATE - POST /www.server.com/api/users
READ   - GET /www.server.com/api/users/1
UPDATE - PUT /www.server.com/api/users
DELETE - DELETE /www.server.com/api/users/1

3. API 레퍼런스 작성

Prerequisite

• URL
• Method
• URL Params
  • URL Param이 있다면 명시
  • Required
  • Optional
• Data Params
  • POST 요청 시 데이터 포맷
• Success Response
• Error Response
• Sample Call
• Notes