Published on

REST API

Authors
  • avatar
    Name
    Na Hyunwoo
    Twitter

평소에 REST API 혹은 RESTful한 API에 대해서 듣게됩니다. 이 용어 자체에는 굉장히 익숙하지만 REST API가 무엇인지 그리고 RESTful한 API가 무엇인지에 대해서 고민해보고 공부해본적은 없는 것 같습니다. 따라서 오늘은 REST API와 더 가까워지기 위해서 REST API에 대해 고민해봤습니다.

REST란 ?

rest

REST의 의미와 탄생

MDN에서는 네트워크 리소스를 정의하고 처리하는 방법을 설명하는 일련의 원칙을 기반으로 하는 아키텍처 스타일(제약조건의 집합)이라고 정의하고 있습니다.

REST에 대한 원칙은 2000년도에 로이 필딩의 박사학위 논문에서 최초로 소개되었습니다. 로이 필딩은 HTTP의 주요 저자중 한 사람으로 HTTP가 제대로 사용되지 못하는 점을 안타까워하며 HTTP의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표하게 됩니다.

따라서 REST 원칙은 HTTP를 잘 활용하기 위한 원칙이라고 할 수 있습니다.

이번 포스팅에서는 REST API가 어떤 원칙을 가지고 있는지에 대해서는 다루지 않고 일반적으로 부르는 REST API는 어떤 구조로 만들어져 있으며 어떤 특징을 가지고 있는지에 대해서 알아보겠습니다. 더 자세한 설명을 듣고 싶으시다면 이곳의 영상을 참고해주세요.

REST API의 구조와 특징

URI는 정보의 자원을 표현해야 합니다.

REST는 REpresentational State Transfer의 약자입니다.

풀어 설명하면 자원(리소스)의 표현에 의한 상태(정보) 전달이라는 뜻입니다.

예시를 들어보겠습니다.

/tools - 툴에 대한 정보
/tools/favorite - 좋아하는 툴에 대한 정보
/tools/recommend - 추천하는 툴에 대한 정보

이 URI만 보더라도 주고받을 정보에 대해 어느정도 예측할 수 있습니다.

자원은 다음과 같은 규칙을 지켜야합니다.

  • 자원은 동사가 아닌 명사를, 대문자보다는 소문자를 사용하여야 합니다.
  • 자원의 도큐먼트 이름은 단수 명사를 사용하여야 합니다.
  • 자원의 컬렉션 이름으로는 복수 명사를 사용해야 합니다.

URI에는 동사를 사용하지 않습니다.

/tools/favorite/delete
/tools/favorite/create

대신에, 자원에 대한 행위를 표현하기 위해서는 HTTP Method(GET, PUT, POST, DELETE 등)를 사용합니다.

아래의 예시들은 제가 실제로 프로젝트 때 사용한 예시들입니다.

조회

Read(조회) - GET
GET /tools
GET /tools/:id
GET /tools/favorite
GET /tools/recommend

생성

Create(생성) - POST
POST /tools/:id/favorite

수정

Update(수정) - PUT
PUT /user
body { id: 1, name: hyunwoo }

삭제

Delete(삭제) - DELETE
DELETE /tools/:id/favorite

위에서 일반적인 REST API가 가진 구조와 특징에 대해서 알아보았습니다. 그러나, 이것은 REST 아키텍처 스타일을 잘 준수한 API가 맞지만 말 그대로 스타일이기 때문에 반드시 이것들을 지켜야만 하는것은 아닙니다. 따라서 각자 상황에 맞게 REST 스타일을 가진 API를 짜는 것이 중요합니다.

한줄 요약

REST는 HTTP를 잘 활용하기 위해서 만들어진 아키텍처입니다.

REST API가 가지고 있는 일반적인 구조와 특징은 다음과 같습니다.

  • URI는 정보의 자원을 표현해야 합니다.
  • URI에는 동사를 사용하지 않고 HTTP Method를 사용해 행위를 표현합니다.

RESTful한 API를 짜게되면 요청을 보내는 URI만으로도 이게 뭘 하는 역할인지 파악 가능합니다. 이를 통해서 코드를 짜고 읽는 사람들은 코드를 이해하기 쉽습니다. 이해하기 쉽기 때문에 communication cost가 낮아집니다. 따라서 생산성이 높아지는 결과를 낳습니다. 따라서 RESTful한 API가 무엇인지 아는것은 중요합니다.

참고

REST 구성 요소

REST는 다음과 같은 3가지로 구성되어 있습니다.

  1. 자원(Resource) - HTTP URI

    모든 자원은 고유한 ID를 가집니다. 이 ID는 서버에 존재하며 클라이언트는 각 자원의 상태를 조작하기 위해 요청을 보냅니다.

  2. 행위(Verb) - HTTP Method

    클라이언트는 URI를 이용해 자원을 지정하고 조작하기 위해 Method를 사용합니다. HTTP 프로토콜에서는 GET, POST, PUT, DELETE와 같은 Method를 제공합니다.

  3. 표현(Representations)

    클라이언트가 서버로 요청을 보내고 서버가 응답으로 보내주는 자원의 상태를 Representation이라고 합니다. REST에서 하나의 자원은 JSON, XML, TEXT, RSS등 여러 형태의 Representation으로 나타낼 수 있습니다.

RESTful API 서버 응답의 구성 요소

  • 상태 표시줄
    • 요청 성공 또는 실패를 알리는 3자리 상태 코드가 있습니다. 2XX 코드는 성공을 나타내고, 4XX, 5XX 코드는 오류를 나타냅니다.
    • 200: 일반 성공 응답
    • 201: POST 메서드 성공 응답
    • 400: 서버가 처리할 수 없는 잘못된 요청
    • 404: 리소스를 찾을 수 없음
  • 메시지 본문
    • 자원에 대한 representation이 담깁니다. JSON, XML과 같은 형식입니다. 예를 들어, Na라는 사람의 이름과 나이를 요청하면 서버는 다음과 같은 JSON representation을 반환합니다. ‘{”name”:”Na”, “age”:”26”}’
  • 헤더
    • 서버, 인코딩, 날짜 및 컨텐츠 유형과 같은 응답에 대한 추가 정보들이 담겨있습니다.

REST의 장단점

장점

  • 쉬운 사용 HTTP 인프라를 그대로 사용하므로 별도의 인프라를 구축할 필요가 없습니다.
  • 클라이언트-서버 역할의 명확한 분리 클라이언트는 REST API를 통해 서버와 정보를 주고받습니다. REST의 특징인 Stateless에 따라 서버는 클라이언트의 Context를 유지할 필요가 없습니다.
  • 특정 데이터 표현 사용 가능 REST API는 헤더 부분에 URI 처리 메서드를 명시하고 필요한 실제 데이터를 body에 표현할 수 있도록 분리시켰습니다. JSON, XML등 원하는 Representation을 사용 가능합니다.

단점

  • 메소드의 한계 REST는 HTTP 메서드를 이용하여 URI를 표현하기 때문에 메서드의 형태가 제한적입니다.
  • 표준이 없음 REST는 설계 가이드일 뿐이지 표준이 아닙니다.

레퍼런스

Day1, 2-2. 그런 REST API로 괜찮은가

REST - 위키백과, 우리 모두의 백과사전

레스트풀

rest-apis

심바의 RESTful API

View on GitHub