🌱 [HTTP/네트워크] REST API

🌊 REST API(Representational State Transfer)

: REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말한다. 즉, REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접그하는 방식을 규정한 아키텍쳐.

 

REST API는 자원, 행위, 표현 3가지 요소로 구성된다. 

구성 요소	내용	표현 방법
자원	자원	URI(엔드포인트)
행위	자원에 대한 행위	HTTP 요청 메서드
표현	자원에 대한 행위의 구체적 내용	페이로드(사용에 있어서 전송되는 데이터)

 

웹 애플리케이션에서는 HTTP 메서드를 이용해 서버와 통신한다.

• GET : 웹 페이지나 데이터를 요청한다.
• POST : 새로운 글이나 데이터를 전송한다.
• DELETE : 저장된 글이나 데이터를 삭제한다.

 

 

RESTful 하다

• 리소스 중심의 올바른 엔드포인트 작성
• 적절한 응답 상태 코드
• 리소스에 대한 정보 기재
• CRUD에 적합한 HTTP 사용

 

REST API 규칙

 

REST API 설계 원칙

1. URI는 리소스를 표현해야 한다.
2. 행위에 대한 정의는 HTTP 요청 메서드를 통해 해야한다.

 

 

Richardson 성숙도 모델

레오나르도 리차드슨은 REST API를 잘 적용하기 위해 4단계 모델을 만들었고 로이 필딩은 이 모델의 모든 단계를 충족해야만 REST API라고 부를 수 있다고 말했으나 실제로 3단계까지 지키기 어려우므로 2단계까지 적용해도 좋은 API디자인이라 볼 수 있고, 이런 경우 HTTP API라고 부른다. 

 

 

REST 성숙도 모델 - 0단계

0단계에선 단순히 HTTP 프로토콜을 사용하기만 해도 된다. 0단계에서는 단 하나의 endpoint를 사용하고, 전달되는 서로 다른 매개변수를 통해 하나의 endpoint에서 여러 동작을 하게 된다. 

단, 이 경우는 해당 API를 REST API라고 할 수 없다. 

 

요청 내용	요청	응답
예약 가능 시간 확인	POST /appointment HTTP/1.1 [헤더 생략] {   "date" : "2023-03-29"   "restaurant" : "오구피자" }	HTTP/1.1 200 OK [헤더 생략] {  "reservation": [   {"restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},  {"restaurant" : "오구피자", "start": "14:00", "end" : "16:00"}  ] }
특정 시간에 예약	POST /appointment HTTP/1.1 [헤더 생략] {  "restaurant" : "오구피자"  "start" : "14:00"  "end" : "15"00"  "patient" : "드림오구" }	HTTP/1.1 200 OK [헤더 생략]

 

Endpoint
Endpoint는 메소드는 같은 URI들에 대해서 다른 요청을 하게끔 구별해주는 항목을 말한다. 

 

REST 성숙도 모델 - 1단계

개별 리소스와의 통신을 준수해야한다.

REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현한다. 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야하며 요청하고 받는 자원에 대한 정보의 응답을 전달해야 한다.

 

0단게에서는 요청에서의 엔드포인트로 모두 /appointment를 사용했으나 1단계에서는 요청하는 리소스에 따라 각기 다른 엔드포인트로 구분하여 사용한다.

 

요청 내용	요청	응답
예약 가능 시간 확인	POST /restaurant/오구피자 HTTP/1.1 [헤더 생략] {   "date" : "2023-03-29" }	HTTP/1.1 200 OK [헤더 생략] {  "reservation": [   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   {"id" : "124", "restaurant" : "오구피자", "start": "14:00", "end" : "16:00"}  ] }
특정 시간에 예약	POST /reservation/123 HTTP/1.1 [헤더 생략] {  "patient" : "드림오구" }	HTTP/1.1 200 OK [헤더 생략] {  "appointment" : {   "reservation" :   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   "patient" : "드림오구"  } }

허준이라는 의사의 예약이 가능한 시간대를 확인하기 위해 endpoint로 /doctors/허준을 지정해주었다. 특정시간대 예약의 endpoint는 예약 가능 시간 확인에서 응답 받은 slots 리소스 중 123이라는 id 리소스가 변경되기 때문에 실제 변경 되는 리소스인 slots/123을 endpoint로 사용하였다.

 

어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각각 다른 엔드포인트를 사용한다.

만약 14시~16시에 예약을 하게 되면 [특정 시간에 예약] 요청은 /slots/124가 될 것이기 때문에 적절한 엔드포인트를 작성하는 것이 중요하다.

 

endpoint 작성 시, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.

 

요청에 따른 응답을 할 때도 사용한 정보와 더불어 성공/실패 여부를 반환해야한다. 

요청 내용	요청	응답
예약 가능 시간 확인	POST /restaurant/오구피자 HTTP/1.1 [헤더 생략] {   "date" : "2023-03-29" }	HTTP/1.1 200 OK [헤더 생략] {  "reservation": [   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   {"id" : "124", "restaurant" : "오구피자", "start": "14:00", "end" : "16:00"}  ] }
특정 시간에 예약	POST /reservation/123 HTTP/1.1 [헤더 생략] {  "patient" : "드림오구" }	HTTP/1.1 409 Conflict [헤더 생략] {  "appointment" : {   "reservation" :   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   "patient" : "드림오구",  "reason" : "해당 시간은 이미 예약되어 있습니다."  } }

HTTP 409 Conflict 응답 상태 코드는 서버의 현재 상태와 요청이 충돌했음을 나타냅니다. 드림오구가 오구피자를 예약하려 하니 이미 예약이 완료되어 요청이 실패되었음을 의미합니다. 붉은색 글씨로 표시한 것과 같이 성공, 실패 여부를 반환해야 합니다.

 

 

REST 성숙도 모델 - 2단계

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

앞서 0단계와 1단계 예시에선 모든 요청 CRUD(Create, Read, Undate, Delete)와 상관없이 POST 메서드를 사용하고 있으나 이는 2단계에 위반한다.

요청 내용	요청	응답
예약 가능 시간 확인	GET /restaurant/오구피자/reservation?date=2023-03-29 HTTP/1.1 [헤더 생략]	HTTP/1.1 200 OK [헤더 생략] {  "slots": [   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   {"id" : "124", "restaurant" : "오구피자", "start": "14:00", "end" : "16:00"}  ] }
특정 시간에 예약	POST /reservation/123 HTTP/1.1 [헤더 생략] {  "patient" : "드림오구" }	HTTP/1.1 201 Creacted Location : reservation/123/appoinment [헤더 생략] {  "appointment" : {   "reservation" :   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   "patient" : "드림오구",  } }

 

 

HTTP 메서드

종류	메서드	메서드 특징
INDEX/RETRIEVE	GET	데이터 조회 BODY를 가지지 않는다. Query를 Body에 담아서 조회 가능하나 지원하지 않는 곳도 있어 권장 ❌ query parameter를 사용하여 필요한 리소스를 전달
CREATE	POST	리소스 생성
REPLACE	PUT	요청한 데이터가 없을 시 추가, 있을 시 덮어쓴다. PUT은 여러번 요청하더라도 결과가 같다(멱등성)
UPDATE	PATCH	전달한 데이터로 수정한다.
DELETE	DELETE	특정 리소스의 삭제를 요청하는데 사용한다.

 

HTTP 메서드 규칙

• GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용한다.
• POST 메서드는 요청마다 새로운 리소스를 생성하고, PUT 메서드(멱등적)는 요청마다 같은 리소스를 반환한다. 
  * 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다.
• PUT 메서드는 교체, PATCH 메서드는 수정의 용도로 사용한다.

 

멱등적
여러 번 적용하더라도 결과가 달라지지 않는 성질

 

REST 성숙도 모델의 2단계까지 적용하면 대체적으로 잘 작성된 API라 한다. 로이 필딩은 3단계까지 만족하지 못한 API는 REST API가 아닌 HTTP API라고 불러야 한다고 주장하나 3단계까지 적용한 사례는 드물다. 

 

 

REST 성숙도 모델 - 3단계

3단계는 HATEOAS(Hypermedia As The Engine Of Application State)라는 하이퍼미디어 컨트롤을 적용한다. 

3단계의 요청은 2단계와 동일하지만 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야한다.

 

요청 내용	요청	응답
예약 가능 시간 확인	GET /restaurant/오구피자/reservation?date=2023-03-29 HTTP/1.1 [헤더 생략]	HTTP/1.1 200 OK [헤더 생략] {  "slots": [   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"}, ....  ],  "links" : {   "appointment" : {     "href" : "http://localhost:5959/slots/123",     "method" : "POST"    }  } }
특정 시간에 예약	POST /reservation/123 HTTP/1.1 [헤더 생략] {  "patient" : "드림오구" }	HTTP/1.1 201 Creacted Location : reservation/123/appoinment [헤더 생략] {  "appointment" : {   "reservation" :   {"id" : "123", "restaurant" : "오구피자", "start": "09:00", "end" : "12:00"},   "patient" : "드림오구",  } "links" : {   "self" : {     "href" : "http://localhost:5959/reservation/123",     "method" : "POST"    },   "cancel" : {     "href" : "http://localhost:5959/reservation/123/cancel",     "method" : "DELETE"    }  } }

 

위처럼 예약을 할 수 있는 링크를 삽입하거나, 예약 후 다시 확인할 수 있는 링크를 작성해 넣기도 한다.

새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트이다. 

 

 

 

OPEN API

: 정해진 이용 수칙(제한사항)이 있는 누구에게나 열려있는 API. 이것이 무제한으로 이용할 수 있는 것은 아니다. 

 

Open API 참고 사이트

 

공공데이터 포털

 

문화공공데이터광장-메인화면

 

공간정보 오픈플랫폼 오픈API

 

네이버 오픈 API 목록 - INTRO

 

Kakao Developers

 

 

 

코드스테이츠 자료와 MDN, 모던 자바스크립트 Deep Dive를 참고하였습니다.