REST API

REST란?👍

`REST란 (Representational State Transfer) 의 약자`

자원(resourece)의 표현(representation)으로 구분하여 해당장원의 상태를 주고받는 모든것을 의미한다✍️

• 즉 REST란
  • HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
  • HTTP Method(POST, GET, PUT, DELETE)를 통해
  • 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.

CRUD Operation이란

CRUD는 대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인 Create(생성), Read(읽기), Update(갱신), Delete(삭제)를 묶어서 일컫는 말로

REST에서의 CRUD Operation 동작 예시는 다음과 같다.

REST 구성 요소

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

• 자원(Resource) : HTTP URI
• 자원에 대한 행위(Verb) : HTTP Method
• 자원에 대한 행위의 내용 (Representations) : HTTP Message Pay Load

REST의 특징

• Server-Client(서버-클라이언트 구조)
• Stateless(무상태)
• Cacheable(캐시 처리 가능)
• Layered System(계층화)
• Uniform Interface(인터페이스 일관성)

REST의 장단점

• **장점**
  • HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
  • HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
  • Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
  • REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
  • 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
  • 서버와 클라이언트의 역할을 명확하게 분리한다.
• **단점**
  • 표준이 자체가 존재하지 않아 정의가 필요하다.
  • 사용할 수 있는 메소드가 4가지밖에 없다.
  • HTTP Method 형태가 제한적이다.
  • 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
  • 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)
• **REST API 설계 예시** 1. URI는 동사보다는 명사를, 대문자보다는 소문자를 사용하여야 한다. Bad Example http://khj93.com/Running/
  Good Example http://khj93.com/run/ 2. 마지막에 슬래시 (/)를 포함하지 않는다. Bad Example http://khj93.com/test/
  Good Example http://khj93.com/test 3. 언더바 대신 하이폰을 사용한다. Bad Example http://khj93.com/test_blog
  Good Example http://khj93.com/test-blog 4. 파일확장자는 URI에 포함하지 않는다. Bad Example http://khj93.com/photo.jpg
  Good Example http://khj93.com/photo

**REST API 성숙도 모델 (Maturity Model)**

Level 0 : 1 URI, 1 HTTP method

level 0은 웹 메커니즘을 사용하지 않고 HTTP를 원격 통신을 위한 전송 시스템으로 사용한다. RPC(Remote Precedure Call) 형태로 리소스 구분 없이 설계된 HTTP API이다.

그저 단순하게 POX(Plain Old XML)를 주고 받는 RPC 스타일 시스템을 말한다. 단 하나의 endpoint를 사용하고, 전달되는 서로 다른 매개변수를 통해 하나의 endpoint에서 여러 동작을 하게 된다. 매개 변수를 body로 전달하기 위해 HTTP method는 POST가 된다.

• Request,Response,CRUD Request

  POST https://api/user
  {
    "function": "getUser",
    "arguments" [
      "1"
    ]
  }

  Response

  HTTP/1.1 200 OK
  {
    "result" {
    	"id": "1"
      "name": "yoonyoung",
    }
  }

  CRUD

  CREATE : POST /api/user
  READ :   POST /api/user
  UPDATE : POST /api/user
  DELETE : POST /api/user

Level 1 : N URI, 2 HTTP method

리소스를 도입한다. 모든 요청을 단일 서비스 endpoint로 보내는 것이 아니라 개별 리소스와 통신하게 된다. 리소스별로 고유한 URI를 사용해서 식별한다.

• Request,Response,CRUD Request

  POST https://api/users/create
  {
    "name": "yoonyoung"
  }

  Response

  HTTP/1.1 200 OK
  {
    "result" {
      "error": "already exist member"
    }
  }

  CRUD

  CREATE : POST /api/users/create
  READ :   GET /api/users/1
  UPDATE : POST /api/users/update
  DELETE : POST /api/users/remove/1

HTTP method는 GET과 POST만 사용하고 있고, Response에서는 error인 경우에도 Status Code를 200으로 전달하고 있다. 또 HTTP headers에 Content-Type이나 Cache 관련 정보를 제공하지 않는다.

Level 2 : N URI, 4 HTTP method

2단계에서는 HTTP method인 GET, POST, PUT, DELETE를 사용해 CRUD를 나타내고 메시지에 Status Code도 담겨 반환한다. GET은 상태를 변화시키지 않는 안전한 Action을 나타내고, 안전하게 얼마든지 호출할 수 있고 매번 같은 결과를 얻도록 한다. 그리고 캐싱을 할 수 있어 사용자 입장에서 성능 향상도 느낄 수 있다.

설명에서는 GET, POST, PUT, DELETE의 4가지 CRUD를 사용한다고 나와있지만, POST와 GET만 사용해도 충족되는 것 같다.

• Request,Response,CRUD Request

  PUT https://api/users
  {
    "name": "yoonyoung"
  }

  Response

  HTTP/1.1 201 Created
  Content-Type: application/json
  {
    "result" {
      "id": "1",
      "name": "yoonyoung"
    }
  }

  CRUD

  CREATE : POST /api/users
  READ :   GET /api/users/1
  UPDATE : PUT /api/users/1
  DELETE : DELETE /api/users/1

2단계에서는 URI에 action이 담기지 않고, 멱등성을 보장하는 GET에는 캐시가 적용된다. Response에는 의미있는 HTTP Status Code가 반환된다. Status Code를 모두 활용할 필요는 없고, 클라이언트 입장에서 200 OK인지, 클라이언트 잘못(400 Bad Request) 인지, 서버 잘못(500 Internal Server Error)인지 정도를 알 수 있도록 전달해주면 충분하다. 다만, 실패일 경우 Body에 왜 실패했는지 정보를 보내주면 좋다.

Level 3 : Hypermedia As Engine of Application State

3단계까지는 와야 진정한 REST API라고 한다. API 서비스의 모든 endpoint를 최초 진입점이 되는 URI를 통해 Hypertext Link 형태로 제공한다. 요즘 API는 API 문서를 제공하지만 단순한 API 목록 제공뿐만 아니라 어떤 request의 다음 request에 필요한 endpoint까지 제공한다. 클라이언트에게 다음에 어떤 동작이 가능한지 힌트를 제공할 수 있다.

다음에 무엇을 할 수 있는지, 그것을 하기 위해 다루어야 할 리소스의 URI를 알려줄 수 있다. 서버가 클라이언트에 문제를 일으키지 않고 URI scheme을 변경할 수 있다. 클라이언트가 링크 URI를 찾는 동안, 서버 팀은 최초 진입점을 제외한 모든 URI 작업을 할 수 있다.

• Request,Response,CRUD,Response Request

  GET https://api/

  Response

  HTTP/1.1 200 OK
  Content-Type: application/json
  {
    "/api/users",
    "/api/users/{userId}/roles",
    "/api/products",
    "/api/..."
  }

  CRUD

  GET https://api/users/1

  Response

  HTTP/1.1 200 OK
  Content-Type: application/json
  {
   "result" {
      "id": "1",
      "name": "yoonyoung",
      "nextActions": {
         "/api/users/{userId}/roles",
       }
    }
  }

OPEN API 와 API KEY

Open API

Open API는 말 그대로 개방형 API

API가 응용 프로그램을 개발할 때 사용하는 인터페이스란 의미이므로 Open API는 프로그래밍에 사용할 수 있는 개방 상태의 인터페이스를 말하고 있다.

다음이나 구글,네이버 등의 포털사이트나 통계청,기상청 등에서 수집한 자료를 응용프로그래밍에 사용할 수 있게 제공하는 서비스이다.

API KEY

API를 이용하기 위해서는 API Key가 필요하다. API Key는 서버의 문을 여는 열쇠이다. (서버를 운용하는데 비용이 필요하기 때문에 서버 입장에서는 아무런 조건 없이 클라이언트에게 데이터 제공할 의무 X)