정의 : REST API는 웹에서 사용되는 데이터(data)나 자원(Resource)을 HTTP URI로 표현하고 HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다.
식당에 갔는데 메뉴판이 이렇다면... 매우 보기 불편하고 주문하기도 어려울 것이다.
➡️ 알아보기 쉽고 잘 작성된 메뉴판이 필요하다!
단순히 HTTP 프로토콜을 사용하기만 해도 되는 단계로, REST API를 작성하기 위한 기본 단계이다.
예제
/appointment
/* 요청 내용: OO 병원의 명의인 허준 선생님의 예약 가능 시간 확인 */ ----------------- 요청 ------------------ POST /appointment HTTP/1.1 [헤더 생략] { "date": "2022-09-13", "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": "09:00", "end": "12:00", "patient": "김코딩" } ------------------ 응답 ------------------ HTTP/1.1 200 OK [헤더 생략]
개별 리소스(Resource)와의 통신을 준수해야 하는 단계로, 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다.
0단계에서는 요청의 엔드포인트를 모두 같게 사용했지만, 1단계에서는 요청하는 리소스에 따라 각기 다른 엔드포인트로 구분해야 한다. (어떤 리소스를 변화시키고 어떤 응답이 제공되는지에 따라 적절한 엔드포인트를 작성)
엔드포인트는 동사, HTTP 메서드, 어떤 행위에 대한 단어 사용은 지양하고 리소스에 집중해 명사 형태로 작성하는 것이 바람직하며, 응답으로는 사용한 리소스의 정보와 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.
예제
/docters/허준
, /slots/123
/* 요청 내용: OO 병원의 명의인 허준 선생님의 예약 가능 시간 확인 */ ----------------- 요청 ------------------ POST /doctors HTTP/1.1 [헤더 생략] { "date": "2022-09-13" } ------------------ 응답 ------------------ 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" : "해당 시간은 이미 예약 마감 되었습니다." } }
앞선 단계에서는 CRUD와 상관없이 POST 메서드를 사용했다. 2단계에서는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.
예제
/* 요청 내용: OO 병원의 명의인 허준 선생님의 예약 가능 시간 확인 (조회)*/ ----------------- 요청 ------------------ GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1 [헤더 생략] ------------------ 응답 ------------------ HTTP/1.1 200 OK [헤더 생략] { "slots" : [ { "id": 123, "doctor": "허준", ...}, { "id": 124, "doctor": "허준", ...} ] }
- 조회(READ) :
GET
(GET 메서드는 body를 가지지 않아서 query parameter를 사용해 리소스를 전달)
/* 요청 내용: 특정 시간에 예약 (생성) */ ------------------ 요청 ------------------ POST /slots/123 HTTP/1.1 [헤더 생략] { "patient": "김코딩" } ------------------ 응답 ------------------ HTTP/1.1 201 Created Location: slots/123/appointment [헤더 생략] { "appointment": { "slot": { "id": "123", "doctor": "허준", ... }, "patient": "김코딩" } }
- 생성(CREATE) :
POST
(새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created 로 명확하게 작성해야 하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있으면 2단계 충족)
3단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다.
응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다. (링크로 새로운 기능에 접근할 수 있도록 함.)
예제
/* 요청 내용: OO 병원의 명의인 허준 선생님의 예약 가능 시간 확인 (조회)*/ ----------------- 요청 ------------------ GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1 [헤더 생략] ------------------ 응답 ------------------ HTTP/1.1 200 OK [헤더 생략] { "slots" : [ { "id": 123, "doctor": "허준", ...}, { "id": 124, "doctor": "허준", ...} ], "links" : { "appointment" : { "href" : "http://localhost:8080/slots/123", "method" : "POST" } } }
/* 요청 내용: 특정 시간에 예약 (생성) */ ------------------ 요청 ------------------ POST /slots/123 HTTP/1.1 [헤더 생략] { "patient": "김코딩" } ------------------ 응답 ------------------ HTTP/1.1 201 Created Location: slots/123/appointment [헤더 생략] { "appointment": { "slot": { "id": "123", "doctor": "허준", ... }, "patient": "김코딩" }, "links" : { "self" : { "href" : "http://localhost:8080/slots/123", "method" : "GET" }, "cancel" : { "href" : "http://localhost:8080/slots/123/cancel", "method" : "DELETE" } } }
정의 : 누구에게나 열려있는 API로, 정부에서 제공하는 공공데이터가 그 예시이다.
예시 :
API Key : API를 이용하기 위해 필요한 서버의 문을 여는 열쇠. (가끔 API key가 필요하지 않은 경우도 있긴 함)
- 웹 개발에서 사용하는 대표적인 클라이언트는 브라우저이다. 이는 서버에 HTTP 요청을 보낼 수 있는 훌륭한 도구이지만, 주로 웹 페이지를 받아오는 GET 요청에 사용한다. (브라우저의 주소창에 URL을 입력하면, 해당 URL의 root-endpoint로 GET 요청을 보냄)
- 테스트를 위해 GET 요청이 아닌 다른 요청을 보내려면, 개발자 도구의 콘솔 창에서 Web API fetch를 사용해야 한다.
- 그렇지만, 테스트를 위해 매번 코드를 작성하는 것은 상당히 번거로운 작업이다. HTTP 요청을 테스트할 수 있는 다양한 API 테스트 도구가 존재한다!
Postman : API 개발을 보다 빠르고 쉽게 구현할 수 있도록 도와주고, 개발된 API를 테스트하여 문서화 및 공유할 수 있도록 도와주는 플랫폼
실습 :
// 주어진 URI
api.openweathermap.org/data/2.5/weather?id={city id}&appid={your api key}
// 서울의 city id는 1835848
api.openweathermap.org/data/2.5/weather?id=1835848&appid={your api key}
| 참고자료 |
- CodeStates - UrClass