Rest API

이유정·2022년 10월 6일

코드스테이츠 TIL

목록 보기

29/62

Rest API가 필요한 이유는?

1) 웹 애플리케이션에서는 'HTTP 메서드'를 이용해 서버와 통신한다.
2) 기계와 기계가 웹을 이용해 통신을 할 때 정해진 규칙이 있다면 얼마나 좋을까?
3)'규격화된 방식의 통신 규칙'이 필요하다!! -> REST API

API vs REST API

1) API

컴퓨터의 기능을 실행시키는 방법

2) REST API

컴퓨터의 기능을 실행시키는 명령
내 컴퓨터가 아니라 남의 컴퓨터를 실행시킨다.
인터넷과 웹을 통해 나의 컴퓨터를 제어할 때 좋은 API를 만들 수 있는가의 결과물
특정 기술이 아니다.
HTTP를 이용해 기계들이 통신할 때, HTTP 가 가진 장점을 최대한 이용할 수 있도록 한다.

REST API

1) 하나하나의 데이터를 TOPIC이라고 할 때

Resource
Collection의 URI
http://example.com/topics
Element의 URI
https://example.com/topics/1
https://example.com/topics/rest

이 URI는 단지 그 정보를 식별할 수 있는 이름일 뿐이고, 정보를 가공하진 못함

2) REST API 는 웹의 통신 규약인 HTTP를 이용하기 때문에 HTTP 메소드를 이용한다.
생성 POST : 새로운 글이나 데이터를 전송
읽기 GET : 웹페이지나 데이터를 요청
수정 PUT : 전제 수정 / PATCH: 부분 수정
삭제 DELETE : 저장된 글이나 데이터를 삭제

3) REST API에 대해 자세히 알아보자

: REST : Representational State Transfer
: 웹 (http)의 장점을 최대한 활용할 수 있는 아키텍쳐다.
: 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다.

감이 안오는가? 밑 이야기로 감을 잡아보자

감 잡아보자
: 클라이언트와 서버 사이에 데이터와 리소스를 요청하고, 응답하기 위한 메뉴판이 필요하다. 이 메뉴판을 보고 클라이언트가 서버에 요청한다.
따라서, HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고 받을 때 잘 작성된 메뉴판이 필요한데, 이 역할을 REST API 가 수행한다.

REST 성숙도 모델 0~3단계

:REST 성숙도 모델은 총 4단계다(0~3).
:이 모든 단계를 충족할 때 REST API 라고 할 수 있다. 그러나 3단계까진 어렵고, 2단계까지만 해도 좋은 API디자인이고, 이런경우를 HTTP API 라고 한다.

퀴즈 !!
REST API는 웹에서 사용되는 데이터나 자원에는 상관없이, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다.(X)
-> REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식입니다.

REST 성숙도 모델 - 0단계

HTTP 프로토콜을 사용하기만 해도 된다. 이 API는 REST API는 아니고, 기본 단계. 단순히 HTTP 프로토콜을 사용하는 것이 REST API 의 출발점

요청 내용
예약 가능한 시간 확인 하고 싶어요!

요청

POST / appointment HTTP /1.1[헤더생략] 
{
 "date" : "2022-08-10"
 "doctor" : "허준"
}

응답

HTTP/1.1 200 OK [헤더생략]
{
 "slots":[
    {"doctor" : "허준", "start": "09:00", "end":"12:00"},
    {"doctor" : "허준", "start": "14:00", "end":"16:00"}
 ]
}

요청 내용
특정 시간에 예약할게요!

요청

POST / appointment HTTP /1.1 [헤더생략]
{
  "doctor": "허준",
  "start" : "14:00",
  "end": "15:00",
  "patient": "김코딩"
}

응답

HTTP/1.1 200 OK [헤더생략]

REST 성숙도 모델 - 1단계

:개별 리소스와의 통신을 준수
REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI 로 표현한다.
따라서 모든 자원은 개별 리소스에 맞는 Endpoint를 사용해서 요청, 응답해야 한다.
0단계에서의 엔드포인트는 모두 /appointment로 지정했지만,,
1단계에서는 각기 다른 엔드포인트로 구분해준다.
(엔드포인트 작성 시 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.)

요청 내용
예약 가능한 시간 확인

요청

POST /doctors/허준 HTTP/1.1[헤더 생략]
{
 "date" : "2022-08-10"
}

응답

HTTP/1.1 200 OK [헤더 생략]
{
  "slots":[
    {"id" :123, "doctor": "허준", "start":"09:00", "end":"12:00"},
    {"id" :124, "doctor": "허준", "start":"14:00", "end":"16:00"}
  ]
}

요청 내용
특정 시간에 예약

요청

POST/ slots/123 HTTP/1.1[헤더 생략]
{
  "patient" : "김코딩"
}

응답

HTTP/1.1 200 OK [헤더 생략]
{
	"appointment" : {
      "slot" : {"id":"123", "doctor": "허준",...},
      "patient" : "김코딩"
 }
}

응답으로 리소스 사용에 대한 실패 응답도 가능하다.
실패 응답

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

REST 성숙도 모델 - 2단계

: CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.

예약 가능한 시간을 알아보는 것은 '조회'로서 GET메서드를 사용해서 요청한다.
(GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용해 필요한 리소스를 전달한다.)
예약을 생성하는 것은 POST 메서드를 사용해서 요청한다.
(응답할 때 새롭게 생성된 리소스를 보내주기 때문에, 201 Created로 작성하고, 관련 리소스를 Location 헤더에 작성된 URI를 통해 클라이언트가 확인할 수 있도록 한다. )

요청 내용
예약 가능한 시간 확인 할게요~

요청

GET /doctors/허준/slots?date=2022-08-19 HTTP/1.1[헤더 생략]

응답

HTTP/1.1 200 OK [헤더 생략]
{
 "slots":[
   {"id":123, "doctor": "허준", ...},
   {"id":124, "doctor": "허준", ...}
 ]
}

요청 내용
특정 시간에 예약 할게요~

요청

POST / slots/123 HTTP/1.1[헤더 생략]
{
 "patient" : "김코딩"
}

응답

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

HTTP 메서드 사용할 때 유의할 점

1) GET 메서드는 서버의 데이터를 변화시키지 않는다.
2) POST 메서드는 요청마다 새로운 리소스를 생성한다. vs PUT 메서드는 요청마다 같은 리소스를 반환한다. (멱등하다)
3) PUT은 전체수정(교체 느낌) vs PATCH 는 부분수정

REST 성숙도 모델 - 3단계

HATEOAS(Hypertext As The Engine Of Application State) 라는 하이퍼미디어 컨트롤을 적용한다. 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크 요소를 삽입해야 한다. (예약을 할 수 있는 링크 삽입, 완료된 예약 확인할 수 있는 링크 삽입)

예약 가능한 시간확인 응답에 추가해준다

"links" :{
  "href": "http://localhost:8000/slots/123",
  "method" : "POST"
}

특정 시간에 예약 응답에 추가해준다.

"links" :{
  "self" : {
    "href" : "http://localhost:8000/slots/123",
    "method" : "GET"
  },
  "content" : {
    "href" : "http://localhost:8000/slots/123/cancel",
    "method" : "DELETE"
  }
}

Open API

정부에서 제공하는 공공데이터
https://www.data.go.kr/ 공공데이터 포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.
: 누구에게나 열려있는 API이지만 무제한 사용을 의미하진 않는다.
: API 마다 이용수칙이 있고, 제한사항(가격이나 정보의 제한)이 있을 수 있다.

예를 들어 https://openweathermap.org/api 날씨API
: 제한적이나마 무료로 날씨 API 사용 가능
: 데이터를 JSON 형태로 응답