1. REST API

1. 개요

REST API는 REpresentational State Transfer약어로 분산 하이퍼 미디어 시스템을위한 소프트웨어 아키텍처의 한 형태입니다.

이것은 로이 필딩이 자신의 박사 학위 논문에서 소개하는 것으로 알려져 있었다.

1. 구성

• 자원 – URI
• 행위(Verb) – HTTP 메소드
• 표현(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 메소드로 표시됩니다.

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

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

// good
DELETE /members/1
POST   /members

⚠️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은 모두 리소스로 표현할 수 있으며 URI로 표현됩니다.

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

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

4. 응답 상태 코드

2. API 성숙도 모델

레벨 0:1 URI, 1 HTTP 메소드

API 서비스에는 하나의 엔드포인트만 제공됩니다.

그런 다음 전달된 매개변수를 통해 하나의 엔드포인트에서 여러 작업을 수행합니다.

매개변수를 Body에 전달하므로 항상 POST를 통해 통신합니다.

요청

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

레벨 1: N URI, 2 HTTP 메소드

REST API 컴포넌트 중 Resource를 도입한 단계이다.

각 리소스에 대해 고유한 URI를 사용하여 식별합니다.

요청

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과 같은 정보가 없습니다.
   
   

레벨 2: N URI, 4 HTTP 메소드

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

요청

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 메서드를 통해 전달합니다.
   
   
2. 201 Created와 같은 적절한 상태 코드를 반환합니다.
   
   또한 Content-Type과 같은 헤더 정보도 포함됩니다.
   
   
3. 현재 대부분의 서비스가 2단계 수준에서 운영되고 있다.
   
   

레벨 3: Hypermedia As Engine of Application State

이 단계에서는, API의 응답만으로 어느 정보를 요구했는지를 알 수 있고(Self-descriptive), 그 정보와 관련된 정보와 관련된 URI를 하이퍼텍스트로서 제공한다.

이는 서버와 클라이언트가 변경되더라도 메시지는 항상 자신을 나타내므로 해석이 가능해야 한다는 의미입니다.

또한 링크는 언제든지 동적으로 변경할 수 있으므로 하이퍼 텍스트로 제공되므로 링크가 변경되어도 언제든지 유연하게 사용할 수 있습니다.

요청

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이 아니라보다 구체적인 사양으로 응답했습니다.
  
  또한 데이터에는 몇 가지 하이퍼링크가 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
• 방법
• URL Params
  • URL Param이 있으면 명시
  • Required
  • 옵션
• Data Params
  • POST 요청 시 데이터 형식
• Success Response
• 오류 응답
• 샘플 호출
• Notes