donghL-dev Velog

Donghun, Lim

Note : 이 글은 지극히 주관적인 생각을 토대로 작성된 글입니다. 혹시나 잘못된 부분이 있다면 메일 또는 코멘트를 통해 알려주시면 감사하겠습니다. 😄 제 메일은 About 탭에서 확인하실 수 있습니다. 📧 
Intro
정말 오랜만에 포스팅을 작성하게 되었다. 이번 포스팅에서는 Restful API에 대한 내용을 정리하고자 한다. 이전부터 정리하고 싶었던 내용이기도 하고, 포스팅을 작성해야지 생각만 계속 하다가 그게 지금까지 미뤄왔던것 같아서 이번 포스팅에서 그 내용을 다루고자 한다. 서론이 길었다. 바로 본론으로 들어가보자.
RESTful API란 무엇인가?
먼저 RESTful이란 용어는 REST 아키텍쳐를 구현한 웹 서비스 또는 REST의 원리와 제약을 따르는 시스템을 지칭하는 용어로 정리할 수 있다.
API는 Application Programing Interface의 약자로써, 어떠한 응용프로그램에서 데이터를 주고 받기 위한 명세라고 정리할 수 있다.
API를 이용해서 어플리케이션에서 필요한 데이터를 요청하거나, 변경하거나 생성할 수 있다. 즉, API는 응용 프로그램에서 데이터를 요청하거나, 변경하거나, 생성하기 위한 인터페이스(명세)라고 이해하면 쉬울 것이다.
어플리케이션에서 어떤 방식으로 정보를 요청할지, 정보를 변경하거나 생성할지에 대한 한 기능에 대한 규격이라고도 정리할 수 있다.
우리는 어떠한 기능에 대한 내부 구현을 알 필요 없이 정리되어 있는 API 문서만 있다면 API 문서를 통해 해당 기능을 어떤식으로 사용할 수 있을지 활용할 수 있을지에 대한 판단을 내릴 수 있다.
REST라는 용어에 -ful이라는 형용사형 어미를 붙여 -한 API라는 표현이 사용된 용어가 RESTful API이다. 즉, REST의 기본 원칙을 성실히 지킨 서비스 디자인은 RESTful 하다라고 표현한 것이다.
정리하면, RESTful API 또는 REST API는 REST 아키텍쳐를 기반으로 서비스 API를 설계 및 디자인한 것을 의미한다.
REST란 무엇인가?
RESTful API가 REST 아키텍쳐를 기반으로 설계된 API라는 것을 위에서 언급하였다. 그럼 위에서 언급한 REST가 무엇인지 알아보자.
REST 아키텍쳐의 정의는 다음과 같다.
  REST는 웹과 같은 분산 하이퍼 미디어 시스템에서 사용하는 통신 네트워크 아키텍쳐로, 
  네트워크 아키텍쳐의 원리 모음을 의미한다.
단순히 정의만 보아서는 이해가 쉽게 안될 수 있다. 정의와는 별개로 내용을 풀어서 정리해보자.
웹은 전송 방식으로 HTTP를 식별 방법으로 URI를 사용한다.
HTTP는 웹에서 GET, POST, PUT, DELETE 등의 메서드를 사용하여 정보를 주고 받는 프로토콜이다.
REST는 HTTP와 URI의 단순하고 간결한 장점을 계승한 네트워크 아키텍쳐를 의미한다.
따라서 다양한 요구사항에 대응하여 때로는 단순하게, 때로는 서버와 클라이언트가 서로 통신하는 리소스에 대해 복잡한 방식으로 상호 작용할 수 있다.
REST가 디자인 패턴이다. 아키텍쳐다 같은 많은 이야기가 존재하는데, 하나의 아키텍쳐로 볼 수 있다. 좀 더 정확한 표현으로 말하자면, REST는 Resource Oriented Architecture이다.
API 설계의 중심에 자원(Resource)이 있고 HTTP Method를 통해 자원을 처리하도록 설계하는 것이다.
RESTful 제약조건
위에서 RESTful API는 REST의 기본 원칙을 성실히 지킨 서비스 디자인이라고 설명하였다. 그럼 REST의 기본 원칙을 성실히 지킨다는 것은 무엇을 의미할까?
REST 아키텍쳐에는 제약조건이 존재한다. 이 제약 조건을 만족할 때 위에서 언급한 REST의 기본 원칙을 성실히 지켰다라고 얘기할 수 있다. REST의 특징이라고 할 수 있는 제약조건들에 대해 알아보자.
Client-Server Architecture
이 제약조건의 기본 원칙은 괌심사의 명확한 분리다. 관심사의 명확한 분리가 선행되면 서버의 구성 요소가 단순화되고 확장성이 향상되어 여러 플랫폼을 지원할 수 있다.
Statelessness
서버에 클라이언트의 상태 정보를 저장하지 않는 것을 말한다. 단순히 들어오는 요청만 처리하여 구현을 더 단순화한다.
단, 클라이언트의 모든 요청은 서버가 요청을 이해하는 데 필요한 모든 정보를 담고 있어야 한다.
서버는 작업을 위한 상태 정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다.
덕분에 서비스의 자유도는 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
Cache Ability
클라이언트의 응답을 캐시할 수 있어야 한다. HTTP의 장점을 그대로 계승한 아키텍쳐가 REST라고 얘기했다. 따라서, HTTP의 캐시 기능도 적용할 수 있다.
Layered System
서버는 중개 서버(게이트 웨이, 프록시)나 로드 밸런싱, 공유 캐시 등의 기능을 사용하여 확장성 있는 시스템을 구성할 수 있다.
Code On Demand(Optional)
클라이언트는 서버에서 자바 애플릿, 자바 스크립트 실행 코드를 전송받아 기능을 일시적으로 확장할 수 있다.
이 제약 조건은 선택 가능하다. 즉, 필수 조건이 아니다.
Uniform Interface
URI로 지정된 리소스에 균일하고 통일된 인터페이스를 제공한다. 아키텍쳐를 단순하게 분리하여 독립적으로 만들 수 있다.
HTTP 표준만 맞는다면, 어떤 기술도 가능한 Interface 스타일을 나타낼 수 있다.
REST API 정의를 HTTP + JSON으로 하였다면 C, Java, Python 등 특정 언어나 기술에 종속받지 않고, 모든 플랫폼에 사용이 가능한 Loosely Coupling 구조를 가진다.
Uniform Interface은 다른 제약 사항과 달리 세부 원칙을 갖고 있다. Uniform Interface에는 세부 원칙으로 다음 4가지 프로퍼티가 존재한다.
Resource Identification In Requests
Resource Manipulation Through Representations
Self-Descriptive Messages
HATEOAS(Hypermedia As The Engine Of Application State)
Resource Identification In Requests
요청에 의한 자원 식별은 웹 기반의 REST에서 자원 접근은 주로 URI를 사용한다는 것을 나타낸다.
즉, 각각의 리소스는 요청에서 식별이 가능해야 한다는 내용을 담고 있다. 예를 들어 아래의 URI에서 정보는 product, 유일한 구분자는 1로 시벽할 수 있다.
  http://localhost:8080/product/1
Resource Manipulation Through Representations
표현을 통한 자원 조작에 대해 알아보자.
클라이언트가 특정 메세지나 메타 데이터를 갖고 있으면 자원을 수정, 삭제하는 충분한 정보를 갖고 있는 것으로 볼 수 있다.
예를 들어 코드에서 content-type은 리소스가 어떤 형식인지 지정한다. 리소스는 HTML, XML, JSON등 다양한 포맷으로 전송된다. 다음 예제에선 포맷을 JSON으로 지정했다.
  http://localhost:8080/product/1
  content-type: aplication/json
Self-Descriptive Messages
각 메세지는 자신을 어떻게 처리해야 하는지 충분히 정보를 포함해야 한다.
즉, API 메세지만 보고, API를 이해할 수 있는 구조를 갖춰야 한다는 것을 의미한다.
Resource, Method를 이용해 무슨 행위를 하는지 직관적으로 이해할 수 있어야 한다.
웹 기반 REST에서는 HTTP Method와 Header를 활용한다. 다음 예제에서는 GET 메서드를 활용하여 /product/1의 정보를 조회해 온다는 것을 표현했다.
  GET http://localhost:8080/product/1
  content-type: aplication/json
HATEOAS(Hypermedia As The Engine Of Application State)
클라이언트에 응답할 때 단순히 결과 데이터만 제공해주기 보다는 URI를 함께 제공해야 한다는 원칙이다.
어플리케이션의 상태는 다른 하이퍼링크를 통해 전이되어야 한다는 원칙으로 서버는 현재 이용 가능한 다른 작업에 대한 하이퍼링크를 포함해서 응답해야 한다.
다음 예제의 JSON에서 _links 프로퍼티가 HATEOAS 원칙의 역할을 수행하고 있음을 알 수 있다.
  {
      "projectIdx": 204,
      "leader": "개설자",
      "leaderIdx": 45,
          "profileImage": "https://deploy.donghun.dev:8083/api/image/USER_DEFAULT_PROFILE_IMG.png",
      "title": "해커톤 팀원 구하기 서비스",
      "summary": "해커톤 팀원을 구하는 웹서비스 만들 팀원 구합니다.",
      "location": "부산",
      "createdDate": "2019-09-30T14:11:05",
      "status": "진행중",
      "_links": {
          "self": {
              "href": "https://deploy.donghun.dev:8083/api/project/204"
          },
          "Leader Profile": {
              "href": "https://deploy.donghun.dev:8083/api/profile/45"
          }
      }
  }
REST API의 구성 요소
위에서 REST가 무엇인지, REST의 제약조건이 무엇인지을 간단하게 알아보았다. 이번에는 REST API를 구성하기 위한 요소에 대해서 알아보자.
REST API는 다음과 같이 구성을 해야 한다.
자원(Resource) : URI
행위(Verb) : HTTP 메소드
표현(Respresentations) : 리소스에 대한 표현 (HTTP Message Body)
Reosurce
자원을 식별하고 표현하기 위해서는 http://myweb/boards와 같은 URI를 사용해야 한다.
URI는 명사를 사용해야 하며, 가급적 동사를 피해야 한다.
동사를 표현할 때는 HTTP 메서드인 GET, POST, PUT, DELETE 등으로 대체해서 사용해야 한다.
물론 모든 경우에 동사를 HTTP 메서드로 대체할 수는 없다.
어디까지나 불필요한 동사를 URI에 포함하는 것을 지양해야 한다는 것이다. 어쩔 수 없는 경우에는 동사가 URI에 포함되어야 할 경우도 있다.
URI에서 명사를 사용할 때 단수형 보다는 복수형을 사용하는 것이 좋다.
/board도 명사로써 사용 가능하지만 복수형인 /boards로 표현하면 컬렉션으로 명확하게 표현할 수 있어서 확장성 측면에서 더 좋다.
Verb - HTTP Method
행위는 HTTP 메서드를 통해서 표현할 수 있다. 위에서 언급했듯이 HTTP 메서드를 통해 동사 부분을 표현할 수 있는데, HTTP 메서드를 통해서 boards의 동사 부분을 표현해보면 다음과 같다.
Idempotent : 한 번 수행하나, 여러 번 수행했을 때 결과가 같은지에 대한 여부.
Method
      의미
      API
      Note
      Idempotent
    
POST
      Create
      /boards
      board 추가 생성.
      NO
    
GET
      Select
      /boards
      board 목록 조회.
      YES
    
PUT
      Update
      /boards/1
      ID가 1인 board 수정.
      YES
    
DELETE
      Delete
      /boards/1
      ID가 1인 board 삭제.
      YES
    
Respresentations
리소스에 대한 표현은 HTTP Message Body를 통해서 리소스를 메세지로 표현할 수 있다.
메세지를 표현할 때 다양한 포맷들이 존재 하는데, 대체로 JSON, XML등의 포맷이 존재한다.
이들 중 어떠한 포맷을 사용해도 상관이 없으나, 최근에는 JSON을 주로 사용하고 있다.
  HTTP POST, http://myweb/boards/
  {
      "boards" : {
          "title" : "test-board-1"
      }
  }
RESTful하게 API를 디자인 했을 때의 장단점은 무엇인가?
앞에서는 REST가 무엇이고, REST API는 어떻게 구성되는지를 살펴보았다. 이번에는 앞에 내용을 정리하는 차원에서 API를 RESTful하게 디자인 했을 때의 장단점이 무엇인지 알아보자.
RESTful하게 API를 디자인했을 때 다음과 같은 이점이 있다.
API를 Open API로 제공하기가 쉽다.
멀티 플랫폼 지원 및 연동이 용이하다.
원하는 타입으로 데이터를 주고 받을 수 있다.
기존의 웹 인프라(HTTP 기반의 웹)를 그대로 사용할 수 있다.
하지만 RESTful하게 디자인된 API가 이점만 존재하는 것이 아니다. 다음과 같은 단점도 가지고 있다.
사용할 수 있는 HTTP 메서드가 4가지 밖에 되지 않는다.
분산 환경에는 부적합하다.
HTTP 통신 모델에 대해서만 지원한다.
마치며
이번 포스팅에서는 REST API에 대해서 알아보았다. REST API는 현재 가장 많이 쓰이고 있는 API 설계 방식이며 그 근간이 되는 REST 아키텍쳐에 대한 내용도 방대하기 때문에 쉽사리 헷갈리기도 하고 이해하기 쉽지 않은 부분도 꽤 있는 내용이다. 본인도 이 부분에 대해서 완벽하게 이해했다고 자신할 수 없기 때문에 그 동안 공부를 통해 알고 있던 내용을 정리하는 차원에서 포스팅을 작성하게 되었다.
개인적으로 REST와 RESTful API에 조금 더 제대로 이해하고 싶다면 그런 REST API로 괜찮은가를 추천한다. 사실 알만한 분들은 아시겠지만 굉장히 유명한 발표 영상이다. 본인도 이 영상을 통해서 처음에 REST API에 대해서 이해하기 시작했었기에 처음에 개념을 잡고 이해하는데 꽤 도움이 될 것이라 생각한다. 이번 포스팅은 여기서 마무리하고 다음에 또 새로운 포스팅을 작성해보도록 하겠다.
Reference
REST API 제대로 알고 사용하기 - TOAST
바쁜 개발자들을 위한 REST 논문 요약

[WEB] RESTful API에 대해서 알아보자. 💡

댓글