REST API 개발을 위한 표준 규격 정의 - 1편. REST API 정의
Tags: webdev, restapi
Published: 2020-12-08 20:18:16

# Overview
Node.js를 기반으로 REST API 서비스를 개발하다보면 API개발에 따른 표준에 대하여 고민을 하게 된다. REST API는 표준 규격이 없다는 점이 큰 이점으로 작동하지만, 협업을 통한 개발을 진행하다보면, 각각의 개발자들의 성향이 유지보수 및 통합에 많은 어려움이 발생할 수 있다.
REST API를 개발하기 전에 자체적인 REST API 개발하기 위한 자체 표준 규격을 정의하기 위하여 REST API 정의와 설계 방안을 통하여 자체적인 표준 규격을 정의하고자 한다.

**1편. REST API 정의**
**2편. REST API 설계 방안**
**3편. REST API 자체 표준 규격 정의**

# 1편. REST API 정의
API는 개인용 컴퓨터가 나오기 전인 컴퓨팅 초기부터 존재하면서 지속적인 발전을 하고 있다. 최근에는 유비쿼터스형 Web-API로 발전까지 설계 편의성과 구현 유현성을 높이기 위해 많은 노력을 하고 있다. 최근 Web-API로 발전하면서 웹환경에서 정보 교환을 표준화하기 이해 SOAP(Simple Object Access Protocol)이라는 프로토콜을 개발하였으나, XML 메시지 형식과 한정적인 요청 방식(HTTP 또는 SMTP)의 한계로 인하여 점차 REST의 사양으로 유행이 이동하고 있다. SOAP는 프로토콜의 한 종류이지만, REST는 아키텍처 스타일인 점도 참고할 만 한다.

REST API를 정의하기 위하여 API와 REST를 먼저 설명을 하고 REST API를 정의를 하고자 한다.

## API의 정의
API는 Application Programming Interface의 약자로, 애플리케이션 소프트웨어를 구축하고 통합하기 위한 정의 및 프로토콜 세트라고 할 수 있다. 즉, 응용프로그램에서 사용할 수 있도록, 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스라고 할 수 있다.
API의 역사는 PC가 나오기 전인 컴퓨팅 초기에 등장하여 주로 운영체제의 라이브러리 형태로 사용되었고, 주로 로컬로 작동을 하였다. 지속적으로 발전한 API는 최근 원격API로 발전하여 웹API로 확대가 되었다. API의 본질은 Decoupling(탈 동조화)이며, Web API의 본질은 Decoupling+Platform agnostic(플랫폼 비종속적)으로 볼 수 있다.

### API 배포 정책
API는 사용권한에따라 3가지 정책으로 나눌 수 있다.

- **프라이빗(Private) 정책**: 내부에서만 사용할 수 있는 API로 일반적으로 기업 내부에서 관리하고, 최대한 제어할 수 있는 API를 뜻한다.-
- **파트너(Partner) 정책**: 특정 비즈니스 파트너와 공유하는 API 정책을 뜻하며, 품질의 저하없이 추가 수익원으로 창출이 가능하다.
- **퍼블릭(Public) 정책**: 모두에게 제공되는 API로, 제3자가 API와 상호작용하는 애플리케이션을 개발하여 혁신을 끌어낼 수 있다.

### API을 통한 혁신 및 장점

API의 활용은 내부의 구현 방식을 알지 못하더라도 제품 혹은 서비스가 서로 커뮤니케이션할 수 있어 클라이언트단 혹은 서비스단의 개발을 간소화하여 시간과 비용을 절약할 수 있으며, 새로운 툴과 제품을 설계하거나 기존 툴과 제품을 관리하는 경우도 유연성을 제공하여 설계, 관리 그리고 사용방법을 간소화하여 혁신의 기회를 제공할 수 있다.
특히 API의 공개로 인하여 파트너 또는 일반사용자에게 새로운 수익 채널을 확보하거나 기존 수익 채널의 확장 기능을 제공할 수 있고 외부 개발을 활용하여 협업을 수행하여 오픈 혁신을 촉진시킬 수 있다.

### REST의 정의

REST는 ‘Representational State Transfer’의 약자로 자원(Resource)을 이름(자원의 표현(representation))으로 구분하여 해당 자원의 상태(정보)를 주고 받는 것을 의미한다.

- 자원(Resource): 해당 소프트웨어가 관리하는 모든 것으로 문서, 그림, 데이터, 해당 소프트웨어 자체를 의미
- 자원의 표현(representation): 그 자원을 표현하기 위한 이름으로 예로 데이터베이스의 학생정보를 자원으로 정의할 때 ’students’를 자원의 표현으로 정의할 수 있다.
- 상태(정보)전달: 데이터가 요청되어지는 시점에서의 자원의 상태(정보) 전달하는 것으로 REST API에서는 JSON 혹은 XML을 활용하여 주고 받는다.

### REST API의 구성

REST의 요소를 파악하는데는 RMM(Richardson Maturity Mode)을 기준으로 이해할 수 있다.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/g5pu3lt5stkdgx7swzrn.png)


### Level 0: The Swamp of POX
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/v1wgvn84sg5i5dq6x03a.png)
웹의 기본 메커니즘을 전혀 사용하지 않는 단계로, HTTP를 통하여 데이터를 주고 받지만 모든 데이터 요청 및 응답과 관련된 정보를 HTTP의 Body 정보를 활용한다.

### Level 1: Resources (URL => 자원)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/5bndb3pvq9rwb4akt2z0.png)

RMM에서 REST를 도입하는 첫단계로, 모든 요청을 단일 서비스 Endpoint로 보내는 것이 아닌 개별 리소스와 통신한다.

### Level 2: HTTP verbs (Http Method => 행위)
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/p7by346pvpxqmh39qyue.png)
Level1의 URL+HTTP method 조합으로 리소스를 구분하는 것으로 응답상태를 HTTP Status code를 활용한다. 대부분의 REST API가 이 단계에서 제공한다. 안전한 오퍼레이션과 안전하지 않는 오퍼레이션간의 강한 분리가 Level 2의 핵심이다.

### Level 3: Hypermedia controls (Representations => 표현)
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/8ke25maheocqyz4mt6fj.png)
일반적으로 HATEOAS(Hypertext As The engine Of Application state)으로 불린다.
Hypermedia란, 하나의 컨텐츠가 텍스트나 이미지, 사운드 같은 다양한 포멧의 컨텐츠를 링크하는 개념으로, Level 3는 특정 API를 요청한 후에 다음 단계로 할 수 있는 작업을 알려주는 것이며, 다음 단계의 작업을 위한 Level3는 특정 API를 요청한 후에 다음 단계로 할 수 있는 작업을 알려주는 것이며, 다음 단계의 작업을 위한 리소스 URL을 알려주는 것이다.

### REST API란

REST는 자원 기반의 구조(ROA, resource oriented Architecture)설게의 중심에 Resource가 있고, HTTP Method를 통해 Resource를 처리하도록 설계된 아키텍처를 의미한다. 이 의미를 웹적으로 설명하자면, HTTP URI(Uniform resource Identifier)를 통해 자원(Resource)를 명시하고, HTTP Method(POST, GET, PUT, DELETE 등)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미할 수 있다.

### RESTful API라 할 수 있는 6가지 주요 제약 조건
1. 클라이언트 서버 아키텍처(Client-Server): REST 아키텍처가 클라이언트, 서버, 리소스로 구성되며 HTTP를 통해 요청을 처리함.   
    * 관심사의 분리(Separation of concerns)원칙 하의 CS구조
    * 데이터 저장은 Servre, UI는 Client
    * 다양한 Platform에 대한 이식성 향상
    * 서버 컴포넌트의 단순화를 통한 확장성 향상.
2. 스테이트리스(Stateless): 요청이 통과하는 서버에는 서버에는 클라이언트 콘텐츠가 저장되지 않으며, 그 대신 세션상태에 대한 정보가 클라이언트에 저장함.
    * 각 Client 요청은 서버에서 요청을 이해하는데 필요한 모든 정보를 담고 있어야 함.
    * REST 설계의 꽃
    * 세션(Session) 정보를 공유할 필요가 없어 효율적인 부하 분산과 확장이 가능.
    * 정보의 흐름에 대한 이해도 높은 가시성과 복잡성을 낮춰서 안정성을 높일 수 있음.
3. 캐시 가능성(Cache): 캐싱으로 일부 클라이언트-서버 간의 상호 작용을 저장할 수 있으며, 이러한 계층은 로드 밸런싱, 공유 캐시 또는 보안과 같은 추가 기능을 제공.
    * 네트워크 효율성 향상이 목표.
    * 자기 서술형메세지(self-descriptiveness)로 인하여 각각의 요청에 대한 응답이 가능하고 이로인하여 독립적으로 처리가 가능하여 Caching이 가능.
4. 계증화된 시스템(Layered System): 추가 계층으로 클라이언트-서버간의 상호 작용을 지정할 수 있으며, 이러한 계층은 로드밸러싱, 공유 캐시 또는 보안과 같은 추가 기능을 제공함.
    * Client는 직저 최종서버에 붙었는지 아니면, Intermediary서버에 붙었는지 알 수 없음.
    * intermediary서버 등을 통해서 로드밸선싱/공유캐시 등을 통해 확장성과 보안성을 향상이 가능함.
5. 코드 온 디멘트(Code-On-demand): 옵션사항으로, 서버가 실행 가능한 코드를 전송하여 클라이언트의 기능을 확대할 수 있음.
6. 통합된 인터페이스(Uniform Interface): RESTful API설계의 핵심사항.
    * 통일된 URI 접근과 제한된 메소드 인터페이스로 통신
    * 요청에서 리소스 식별(Identification of resource): 리소스의 요청에서 식별이 가능하며, 클라이언트로 반환된 표현으로부터 분리됨
    * 표현을 통한 리소스 조직(manipulation of resources through representations): 클라이언트가 리소스를 나타내는 파일을 수신. 이 표현에는 조작 또는 삭제를 허용할 수 있도록 충분한 양의 정보가 포함되어야 함.
    * 자기 기술적 메시지(Self-Descriptive message): 클라이언트에 반환되는 각 메시지에 클라이언트가 정보를 어떻게 처리해야할지 설명하는 정보가 충분히 포함되어야 한다.
    * 로이 필딩의 논문에서는 3가지를 말하고 있다.  
        * 각각 요청에 해당하는 정보가 있어야 한다.
        * 표준 Method(POST, GET, PUT, DELETE 등)와 미디어 유형을 사용하여 명확하게 파악이 가능하게 사용
        * Response에 캐시 가능성을 지정.
    * 애플리케이션 상태 엔진에서의 아이퍼미디어(HATEOAS): 리소스를 할당한 후 REST 클라이언트가 하이퍼링크를 통해 현재 사용가능한 기타 모든 작업을 찾을 수 있어야 함. (사전 정의된 Interface로 통신하는 SOA와 구분되는 지점임)