1. REST API
1) 개요
- 웹 애플리케이션에서는 HTTP 메서드를 이용해 서버와 통신한다
- GET을 통해 웹 페이지나 데이터를 요청한다
- POST로 새로운 글이나 데이터를 전송한다
- DELETE로 저장된 글이나 데이터를 삭제한다 - 클라이언트와 서버가 HTTP 통신을 할 때는 어떤 요청을 보내고 받느냐에 따라 메서드의 사용이 달라진다
- REST API에서 REST는 “Representational State Transfer”의 약자이다
- 로이 필딩의 박사학위 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로써 처음 소개되었다 - REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다
2) 역활
- 클라이언트와 서버 사이에는 데이터와 리소스를 요청하고 요청에 따른 응답을 전달하기 위한 도구 필요하다
- 도구를 통해 클라이언트는 서버에 필요한 것을 요청하고, 이에 대한 응답을 다시 서버에서 클라이언트로 전송할 수 있다
- HTTP 프로토콜 기반으로 요청과 응답에 따라 리소스를 주고받는 작업을 API가 수행해야 한다
- 클라이언트와 서버 간에 서로 잘 알아볼 수 있도록 작성하는 것이 중요하다
2. REST API를 디자인하는 방법
- REST API를 작성에는 몇 가지 지켜야 할 규칙들이 있다
- 로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다
- 로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했다
- 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우 HTTP API 라고 한다
- 리차드슨의 REST 성숙도 모델은 총 4단계(0~3단계)로 나누어진다
1) REST 성숙도 모델 - 0단계
- 0단계에서는 HTTP 프로토콜을 사용하기만 해도 된다
- 0단계의 경우에는 해당 API를 REST API라고 할 수는 없다
- 0단계는 좋은 REST API를 작성하기 위한 기본 단계이다 - 허준이라는 의사의 예약 가능한 시간을 확인하고, 어떤 특정 시간에 예약하는 상황의 예제
- HTTP 프로토콜을 사용하고 있다
- 단순히 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 [헤더 생략] |
2) REST 성숙도 모델 - 1단계
- 1단계에서는 개별 리소스와의 통신을 준수해야 한다
- REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다
- 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 한다
- 모든 자원은 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다 - 0단계에서는 모든 요청에서 엔드포인트로 /appointment 를 사용하였다
- 1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용해야 한다
- 1단계 예제
- 예약 가능 시간 확인이라는 요청의 응답으로 받게 되는 자원(리소스)은 허준이라는 의사의 예약 가능 시간대이다
: 예약 가능 시간 확인 요청 시 /doctors/허준이라는 엔드포인트를 사용하였다
- 특정 시간에 예약하게 되면, 실제 slot이라는 리소스의 123이라는 id를 가진 리소스가 변경된다
: 특정 시간 예약이라는 요청에서는 /slots/123으로 실제 변경되는 리소스를 엔드포인트로 사용하였다
요청 내용 | 요청 | 응답 |
예약 가능 시간 확인 | 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" : { "slots" : { "id" : 123, "doctor" : "허준", ... } , "patient" : "김코딩" } } |
- 어떤 리소스를 변화시키는지 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용해야 한다
- 적절한 엔드포인트를 작성하는 것이 중요하다
- 엔드포인트 작성 시에는 동사, HTTP 메서드, 어떤 행위에 대한 단어 사용은 지양한다
- 리소스에 집중된 명사 형태의 단어로 작성하는 것이 적당하다 - 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 리소스 사용에 대한 성공/실패 여부를 반환해야 한다
- 김코딩 환자가 허준 의사에게 9시에 예약을 진행하였으나, 해당 시간에 예약이 불가능할 경우에는 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다
요청 내용 | 요청 | 응답 |
예약 가능 시간 확인 | 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 [헤더 생략] { "appointmentFailure" : { "slots" : { "id" : 123, "doctor" : "허준", ... } , "patient" : "김코딩" , "reason" : "해당 시간은 이미 다른 예약이 있습니다" } } |
3) REST 성숙도 모델 - 2단계
- 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다
- 0단계와 1단계 예시에서는 모든 요청을 CRUD에 상관없이 POST로 하고 있다
- REST 성숙도 모델 2단계에 따르면 CRUD에 따른 적합한 메서드를 사용한 것이 아니다 - 예약 가능 시간 확인은 예약 가능한 시간을 조회(READ)하는 행위를 의미한다
- 조회(READ)하기 위해서는 GET 메서드를 사용하여 요청을 보낸다
- GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달한다 - 특정 시간 예약은 해당 특정 시간에 예약을 생성(CREATE)한다는 것과 같다
- 예약을 생성(CREATE)하기 위해서는 POST 메서드를 사용하여 요청을 보내는 것이 적당하다 - 2단계에서는 POST 요청에 대한 응답이 어떻게 반환되는지도 중요하다
- 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드도 201 Created 로 명확하게 작성해야 한다
- 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있어야 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이다
요청 내용 | 요청 | 응답 |
예약 가능 시간 확인 | POST/doctors/허준/slots?data=2022-08-10 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" : { "slots" : { "id" : 123, "doctor" : "허준", ... } , "patient" : "김코딩" } } |
※ 메서드 사용 규칙
- GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다
- POST 메서드는 요청마다 새로운 리소스를 생성한다
- PUT 메서드는 요청마다 같은 리소스를 반환한다
- 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다
- 멱등성을 가지는 메서드 PUT 과 그렇지 않은 POST는 구분하여 사용해야 한다 - PUT 과 PATCH 도 구분하여 사용해야한다
- PUT은 교체의 용도로 사용한다
- PATCH는 수정의 용도로 사용한다 - HTTP request methods : https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
HTTP request methods - HTTP | MDN
HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred to as HTTP verbs. Each of them implements a different semantic, but som
developer.mozilla.org
4) REST 성숙도 모델 - 3단계
- 3단계는 HATEOAS(Hypertext As The Engine Of Application State)라고 표현되는 하이퍼미디어 컨트롤을 적용한다
- 3단계의 요청은 2단계와 동일하다
- 3단계의 응답은 리소스의 URI를 포함한 링크 요소를 삽입하여 작성하는 것이 다르다
- 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다
요청 내용 | 요청 | 응답 |
예약 가능 시간 확인 |
POST/doctors/허준/slots?data=2022-08-10 HTTP/1.1 [헤더 생략] |
HTTP/1.1 200 OK [헤더 생략] { " slots" : [ { "id" : 123, "doctor" : "허준", ... } , ... ] , "links" : { "appointment" : { "href" : "http://llocalhost:8080/slots/123", "method" : "POST" } } } |
특정 시간 예약 |
POST/slots/123 HTTP/1.1 [헤더 생략] { "patient" : "김코딩" } |
HTTP/1.1 201 Created Location : slots/123/appointment [헤더 생략] { "appointment" : { "slots" : { "id" : 123, "doctor" : "허준", ... } , "patient" : "김코딩" } , "links" : { "self" : { "href" : "http://llocalhost:8080/slots/123", "method" : "GET" } "cancel" : { "href" : { "http://llocalhost:8080/slots/123/cancel", "method" : "DELETE" } } } |
- 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 중요 포인트이다
- 예약 가능 시간을 확인한 후에는 그 시간대에 예약을 할 수 있는 링크를 삽입할 수 있다
- 특정 시간에 예약을 완료하고 나서 예약을 다시 확인할 수 있도록 링크를 작성할 수 있다
▶ 5가지의 기본적인 REST API 디자인 가이드 : https://blog.restcase.com/5-basic-rest-api-design-guidelines/
5 Basic REST API Design Guidelines
As soon as we start working on an API, design issues arise. Robust and strong design is a key factor for API success. A poorly designed API will indeed lead to misuse or – even worse – no use at all by its intended clients: application developers. Crea
blog.restcase.com
▶ 호주 정부 - API 설계 표준 : https://api.gov.au/sections/definitions.html#api
api.gov.au
Definitions API In the context of this API Design Standard, an API (Application Programming Interface) is defined as a RESTful API. A RESTful API is a style of communication between systems where resources are defined by URI and its operations are defined
api.gov.au
▶ API 디자인 가이드 : https://cloud.google.com/apis/design?hl=ko
API 디자인 가이드 | Google Cloud
의견 보내기 API 디자인 가이드 2017년 2월 21일에 게시됨. 변경 로그 소개 본 문서는 네트워크 API를 위한 종합 디자인 가이드입니다. 2014년부터 Google 내부에서 사용되었으며, Cloud APIs 및 기타 Google
cloud.google.com
▶ Microsoft REST API Guidelines : https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
GitHub - microsoft/api-guidelines: Microsoft REST API Guidelines
Microsoft REST API Guidelines. Contribute to microsoft/api-guidelines development by creating an account on GitHub.
github.com
'Network' 카테고리의 다른 글
네트워크 - HTTP (0) | 2022.06.08 |
---|---|
네트워크 - 브라우져(Browser) (0) | 2022.06.08 |
네트워크 - 클라이언트(Client) (0) | 2022.06.07 |