Rest API가 뭐에요?

HeeSeok·2023년 5월 24일

CS

목록 보기

1/1

🚩Rest API란?

REST API는 REST 아키텍처를 기반으로 구현되는 API로서 자원, 행위, 표현의 세 가지 요소로 구성되어 있습니다. 또한 REST API를 올바르게 구현하기 위해서는 6가지 제약조건을 준수해야 합니다. 그렇다면 3가지 구성 요소 와 6가지 제약조건에 대해서 자세히 살펴보겠습니다.

🚩Rest API 구성 요소

🏁자원

URI를 사용하여 자원을 표현합니다.
모든 자원에는 고유한 ID가 존재하고 이 자원은 Server에 존재합니다.

🏁행위

자원에 대한 어떤 행위를 할 것인지 HTTP Method를 사용해 나타냅니다.(Get, Post, Put, Patch, Delete)

🏁표현

Client와 Server가 데이터를 주고받는 형태로 대표적으로 Json, XML, HTML등이 있습니다.

위 사진은 구글 Gmail의 Label API문서를 가져왔습니다. Label API문서를 통해 3가지 구성요소를 작성해보겠습니다.

자원 : https://gmail.googleapis.com/gmail/v1/users/{userId}/labels/{id}
행위 : GET
표현 : JSON

🚩Rest API 제약조건

🏁Client-Server(클라이언트-서버)

클라이언트와 서버가 서로 분리되어 있어야 함을 의미합니다.

Server(서버)
자원(API)을 제공하며 클라이언트 요청에 따라 데이터를 처리하고 응답을 보내는 역할을 합니다.
Client(클라이언트)
서버에 요청을 보내고 응답을 받으며 사용자 인증, 세션, 로그인 정보 등을 관리하며 이러한 정보를 사용하여 서버에 요청을 보낼 수 있습니다.

🏁Stateles(무상태성)

서버는 클라이언트의 정보를 저장, 관리하지 않으며 요청만을 처리합니다.

🏁Cacheable(캐시 가능)

클라이언트가 서버로부터 받은 응답을 캐시에 저장하여 재사용할 수 있음을 의미합니다.

HTTP 프로토콜을 사용해 HTTP가 가진 캐싱 정책이 적용 가능합니다.

🏁Layered System(계층형 구조)

클라이언트는 최종 서버에 직접 연결되었는지 중개 서버에 연결되었는지 알 수 없습니다.

🏁Uniform Interface(인터페이스 일관성)

통일된 Interface를 통해 어떤 플랫폼에서도 사용이 가능해야 하며 이를 위해 4가지 제약 조건을 만족해야 합니다.

Identification of resources

서버의 자원은 URI로 식별되어야 합니다.

Manipulation of Resources Through Representations

클라이언트가 HTTP 메서드를 사용해 서버의 자원을 조작(CRUD) 할 수 있으며 조작을 위해 JSON, XML 등의 표현 형식을 사용해야 합니다.

Self-descriptive Messages

메시지가 스스로를 설명할 수 있는 구조를 가져야 함을 의미합니다.

위 사진은 카카오의 Open API 문서입니다. 클라이언트는 api 명세만으로 api를 알 수 있습니다.

HATEOAS(Hypermedia as the Engine of Application State)

애플리케이션 상태를 이동할 때 하이퍼링크를 통해 가능한 행동들을 파악하고 그에 따라 요청을 보낼 수 있어야 한다를 의미합니다.

GET /users/123 HTTP/1.1
Host: https://api.example.com

다음과 같은 API 명세가 있다고 가정해보겠습니다. HATEOAS를 적용한 API 응답결과는 다음과 같습니다.

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "links": {
    "self": {
      "href": "https://api.example.com/users/123"
    },
    "friends": {
      "href": "https://api.example.com/users/123/friends"
    },
    "edit": {
      "href": "https://api.example.com/users/123",
      "method": "PUT"
    },
    "delete": { 
      "href" :  "https://api.example.com/users/123" , 
      "method" :  "DELETE" 
    } 
  } 
}

links 객체 안에 사용자 정보를 조회, 수정 등의 관련된 작업을 수행할 수 있는 링크 정보들이 포함되어 있습니다. 이를 통해 클라이언트는 각 링크가 어떤 작업에 대응되는지 알 수 있고 이러한 정보를 바탕으로 동적으로 애플리케이션 상태를 변경할 수 있습니다.

🏁Code on demand(옵션)

서버는 클라이언트에 실행 가능한 코드를 제공할 수 있어야 합니다. (이 규칙은 선택 사항입니다.)

예를 들어 Swagger를 사용해 클라이언트는 서버가 제공하는 API를 확인하고 테스트할 수 있습니다.

🚩API 디자인 가이드

마지막으로 Restful API 디자인 가이드를 소개하며 글을 마치겠습니다.

URI는 동사보다는 명사를 사용합니다
ex) /getUsers => X / users => O
URI는 계층 구조를 가지며 자원 간 관계를 나타내야 합니다.
ex) /users/1/posts
URI에 소문자를 사용해 일관성을 유지합니다.
적절한 HTTP 메서드와 HTTP 상태 코드를 사용합니다.
ex) 게시물 생성(post) / Response(201)
API가 변경될 가능성이 있으므로 버전 관리를 통해 호환성을 유지할 수 있도록 해야 합니다.
ex) /api/v1/users
URI에 파일 확장자를 포함하지 않습니다.
ex) users/image.png => X / users/image => O
쿼리 매개변수를 사용하여 자원 목록을 필터링, 정렬 및 페이징할 수 있게 해야 합니다.
ex) /users?sort=asc&page=2&limit=10

🚩Reference

HeeSeok