TIL Day 36 REST API

클라이언트와 서버의 통신을 담당하는 API를 알아보자.
Google, MS 같은 대형 IT기업은 API를 어떻게 작성하고 있을까요?

혼자서 웹사이트를 만들고 관리한다면 API에 대한 규칙이 필요하지 않습니다. 그러나 회사에서는 팀 단위로 서비스를 개발하기 때문에 사소한 것 하나라도 규칙이 있어야 소통이 원활합니다.

AG

• REST API에 대해 이해할 수 있다.
• Postman이 무엇인지 이해하고 사용할 수 있다.

REST API

웹 애플리케이션에서는 HTTP 메소드(GET/POST/PUT/DELETE 등) 을 활용하여 요청과 응답을 통해 데이터를 주고 받는다. 요청과 응답을 할 때는 '제대로 보내고 받을 수 있는' 일종의 규약이 존재한다. 이를 REST API(Representational State Transfer)의 약자로, 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말한다.

그러면 규약에 맞는 REST API를 어떻게 만들 수 있을까?

좋은 REST API를 디자인 하는 방법

REST 성숙도 모델 - 0단계

단순히 HTTP 프로토콜을 사용한다.

req : POST/appointment HTTP/1.1
res : HTTP/1.1 200 OK

0단계 HTTP 프로토콜이 적절하지 않은 이유 : 요청한 내용의 특징을 정확히 알 수 없다.

REST 성숙도 모델 - 1단계

개별 리소스와의 통신을 준수한다.
쉽게 말하면, 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야 한다는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계에서 의미하는 바다.

req : POST/doctors/허준 HTTP/1.1
[헤더 생략]
{"date" : "2022-08-10"
}
res : HTTP/1.1 200 OK
[헤더 생략]
{
  "slots" : [
    {"id" : 123, "doctor" : "허준", "start" : "09:00", "end" : "12:00"},
    {"id" : 124, "doctor" : "허준", "start" : "14:00", "end" : "16:00"}

req : POST/slots/123 HTTP/1.1
    [헤더 생략]
  {
    "patient" : "김코딩"
  }
res : HTTP/1.1 200 OK
[헤더 생략]
  {
    "appointment" : {
      "slot" : {"id" : 123, "doctor" : "허준", ~},
       "patient" : "김코딩"
   }
  }
//또는 
res : HTTP/1.1 409 Conflict
[헤더 생략]
    {
      "appointmentFailure : {
      "slot" : {"id" : 123, "doctor" : "허준",~},
       "patient" : "김코딩",
       "reason" : "해당 시간은 이미 예약되어 있습니다."
       }
     }

0단계에서는 모든 요청을 엔드포인트로 /appointment 로 사용했는데, 1단계에서는 예약 가능한 시간 확인 이라는 요청의 응답을 받게 되는 리소스는 허준이라는 의사의 예약 가능한 시간이다. 따라서 /doctor/허준 이라는 엔드포인트를 사용하게 된 것이다.
또한 특정 시간에 예약하면, 실제 slot이라는 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에 /slot/123 으로 실제 변경되는 리소스를 엔드포인트로 사용했다.

이처럼 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에, 적절한 엔드포인트 사용이 중요하다.

REST 성숙도 모델 - 2단계

2단계에서는 CRUD에 맞게 적절한 API를 작성하는 것을 중점으로 둔다.

위의 예시처럼 예약 가능한 시간을 READ하고, 특정시간에 예약을 CREATE한다는 것과 같다. 그렇기 때문에 READ하기 위해선 GET 메소드를 사용하여 요청을 보내고, GET은 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달한다.

예약을 CREATE 하기 위해선 POST 메소드를 사용하여 요청을 보내는 것이 바람직하다.

req : GET/doctors/허준/slots?date=2022-08-10 HTTP/1.1
[헤더 생략]
res : HTTP/1.1 200 OK
{
  "slots" : [
    {"id" : 123, "doctors" : "허준", ~},
    {"id" : 124, "doctors" : "허준", ~}
    ]
}

req : POST/slots/123 HTTP/1.1
[헤더 생략]
{
  "patient" : "김코딩"
}
res : HTTP/1.1 201 Created
Location : slots/123/appointment
[헤더 생략]
{
  "appointment" : {
    "slot" : {"id":123, "doctor" : "허준", ~ },
    "patient" : "김코딩"
  }
}

위의 메소드 사용 규칙을 정리해보겠다.
GET : 서버의 데이터를 변화시키지 않은 요청에 사용해야 한다.
POST : 요청마다 새로운 리소스를 생성한다.
PUT : 요청마다 새로운 리소스를 반환한다. (업데이트)(idempotent)
PATCH : 요청한 부분 리소스를 업데이트 한다.

2단계 조건을 충족한다면 REST API라고 부를만 하다.

3단계는 패스

Open API