REST API

REST API

---

• REST API 에서 REST는 Representational State Transfer 의 약자로 소프트웨어 프로그램 아키텍처의 한 형식이다.
• 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 클라이언트와 서버 사이에 데이터와 리소스의 요청과 응답을 정의하는 방식을 의미한다.
• HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하며, REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다. 즉, 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다.

 

 

REST 성숙도 모델

---

• 레오나르드 리차드슨이 만든 REST API 모델로, 성숙도를 총 4단계(0~3단계)로 나누어져서 각 단계를 달성할 수록 REST API에 가까워진다.
• 2단계까지만 적용해도 좋은 API 디자인이라고 말하며, 2단계 부터 HTTP API 라고도 부른다.

 

REST  0단계

• HTTP 프로토콜을 사용하기만 해도 되는 REST API를 작성하기 위한 가장 기본 단계.
• 단 하나의 endpoint를 사용하고, 전달되는 서로 다른 매개변수를 통해 하나의 endpoint에서 여러 동작을 하게 된다.
• 매개 변수를 body로 전달하기 위해 HTTP method는 POST가 된다.

요청

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

//응답
HTTP/1.1 200 OK
{
  "result" {
  	"id": "3"
    "name": "babaeytu",
  }
}

 

CRUD

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

 

REST  1단계

• 개별 리소스와의 통신을 준수하기위해, 모든 자원은 개별 리소스에 맞는 Endpoint를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야한다.
• 또한, 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야한다.
• Endpoint 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

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

//응답
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

 

 

REST  2단계

• HTTP method인 GET, POST, PUT, DELETE,즉 CRUD에 맞게 적절한 HTTP 메소드를 사용하는 것에 중점을 둔다.
• 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인 할 수 있도록 해야, 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 보고, HTTP API라 부른다.
• READ하기 위해서는 GET 메서드를 사용하여 요청을 보내고, 이때 GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달한다.
• CREATE기 위해서는  POST 메서드를 사용하여 요청을 보내야 하며, POST 요청에 대한 응답이 어떻게 반환되는지가 중요하다. 
• 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created 로 명확하게 작성해야 하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 해야한다.
• PUT 메서드는 POST 메서드랑 비슷하게 요청을 보낼때 사용한다. 그러나 PUT메서드는 요청마다 같은 리소스를 반환하는 멱등성을 가지고 있기에 구분하여 사용해야 한다.
• 또한 PUT은 교체, PATCH는 수정의 용도로 사용함을 구분해야 한다.

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

//응답
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

 

 

REST - 3단계

• HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다.
• 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.  이를 통해 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소로 사용할 수 있다
• 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.
• 즉,  단순한 API 목록 제공뿐만 아니라 어떤 request의 다음 request에 필요한 endpoint까지 제공한다

//요청
GET https://api/users/1

//응답
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는 정해진 이용 수칙과 제한사항(가격, 정보의 제한 등)을 준수하면 누구에게나 열려있는 API이다.
• 주로 공공기관에 정부에서 제공하는 공공데이터가 이에 포함된다. 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인가능하다.
• API Key는 API를 이용하기 위해 서버에 접속하는 데 필요한 열쇠이다. 
• 서버를 운용하는 데에 비용이 발생하기 때문에 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무는 없기에 만들어 졌다.
• API Key가 필요한 경우에는 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다