오늘의 목표

1. Rest-API
2. Open API
3. Postman

---

내용

Rest-API

웹 애플리케이션에서는 HTTP메서드를 이용해 서버와 통신합니다. GET을 통하여 데이터를 요청하고, POST를 통하여 데이터를 전송합니다. 어떤 요청을 하느냐에 따라 HTTP 메서드의 사용이 달라집니다.

각 HTTP메서드를 규칙성 있게 작성하기 위해 REST-API를 사용합니다. GET으로 데이터를 전송하는 등의 행위를 막기 위해 사용합니다. HTTP메서드 사용시 강제 되지는 않습니다만 더 성숙한 REST-API를 구현하는 것이 더 옳바른 요청과 응답을 주고 받는 것 입니다.

REST API에서 REST는 Representational State Transfer의 약자로, 로이 필딩의 박사학위 논문에서 웹의 장점을 최대한 활용할수 있는 아키텍처로써 처음 소개되었습니다. REST API는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고 HTTP프로토콜을 통해 요청과 응답을 정의하는 방식입니다.

REST성숙도는 0~3단계로 총 4단계로 이루어 집니다.

로이 필딩은 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장하였지만, 실제로 3단계까지 지키기는 어렵기 때문에 2단계 까지만 적용해도 좋은 API 디자인이라고 볼수 있고, HTTP API라고 부릅니다.

REST 성숙도 - 0단계

0단계에서는 단순하게 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"}
    ]
}

특정 시간에 예약

요청

PSOT /appointment HTTP/1.1
[헤더 생략]

{
	"doctor":"허준",
    "start":"14:00",
    "end":"15:00",
    "patient":"김코딩"
}

응답

HTTP/1.1 200 OK
[헤더 생략]

리소스와 응답이 서로 겹쳐져 있어서 HTTP메서드가 다르지만 결과가 같음을 확인할 수 있습니다. 따라서 0단계 입니다.

REST 성숙도 - 1단계

REST API에서는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현해야 합니다. 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야한다는것과 받은 요청에 대해 자원에 대한 정보를 응답해야 하는것이 1단계에서 의미하는 바입니다.

/appointment를 엔드포인트로 사용하였지만 각기 다른 리소스는 다른 HTTP URI를 사용해야합니다.
또 리소스에 대한 정보를 반환하여야 합니다.

예약 가능한 시간 확인

요청

POST /doctors/허준 HTTP/1.1
[헤더 생략]

{
	"date": "2022-08-10",
}

응답

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

특정 시간에 예약

요청

PSOT /slots/123 HTTP/1.1
[헤더 생략]

{
    "patient":"김코딩"
}

응답

HTTP/1.1 200 OK
[헤더 생략]

{
	"appointmentFailure": {
    	"slot": { "id": "123", "doctor": "허준",...},
        "patient": "김코딩",
        "reason": "해당 시간은 이미 예약되어 있습니다."
    }
}

REST 성숙도 - 2단계

REST성숙도 2단계에서는 CRUD에 맞게 HTTP메서드를 사용하는것에 중점을 둡니다.

CRUD	HTTP 메서드
CREATE	POST
READ	GET
UPDATE	PUT
DELETE	DELETE

단순히 조회하는 예약 가능한 시간 확인에서는 POST가 아닌 GET 메서드를 호출하고 BODY가 아닌 쿼리문에 내용을 포함하여 이용합니다.
새로운 리소스를 만드는 POST HTTP메서드는 200 ok가 아닌 201 created로 명확하게 응답을 돌려주어야 하며 새롭게 만들어진 리소스의 위치를 LOCATION:xxxxx....를 헤더에 추가하여 URI를 통해 확인할 수 있도록 해야 REST 성숙도 2단계를 충족합니다.

예약 가능한 시간 확인

요청

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

응답

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

특정 시간에 예약

요청

PSOT /slots/123 HTTP/1.1
[헤더 생략]

{
    "patient":"김코딩"
}

응답

HTTP/1.1 201 Created
Location: slots/123/appointment
[헤더 생략]

{
	"appointmentFailure": {
    	"slot": { "id": "123", "doctor": "허준",...},
        "patient": "김코딩",
    }
}

메서드	설명
GET	서버의 데이터를 변환시키지 않는 요청에 사용
POST	요청마다 새로운 리소스를 생성합니다.
PUT	요청마다 리소스를 교체하고, 멱등(같은 리소스 반환)입니다.
PATCH	일부를 수정합니다.
DELETE	해당 리소스를 삭제합니다.

보통 REST 성숙도 3단계를 적용한 경우는 극히 드물기 때문에 보통 2단계만 충족하여도 REST API라고도 부릅니다.

REST 성숙도 - 3단계

마지막 단계는 HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 미디어 컨트롤을 적용합니다. 2단계 + 리소스의 URI를 포함한 링크 요소를 삽입하여 작성합니다.

예약 가능한 시간 확인

요청

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

응답

HTTP/1.1 200 OK
[헤더 생략]
{
	"slots": [
    	{"doctor" : "허준", "start": "09:00", "end": "12:00"},
        {"doctor" : "허준", "start": "14:00", "end": "16:00"}
    ],
    "links": {
    	"appointment": {
        	"href": "http://localhost:8080/slots/123",
            "method": "POST"
        }
    }
}

특정 시간에 예약

요청

PSOT /slots/123 HTTP/1.1
[헤더 생략]

{
    "patient":"김코딩"
}

응답

HTTP/1.1 201 Created
Location: slots/123/appointment
[헤더 생략]

{
	"appointmentFailure": {
    	"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"
        }
	}
}

응답에 들아가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있습니다. 프론트엔드 개발자들이 해당 링크를 활용하여 좀더 많은 기능들을 사용자들에게 제공할 수 있을 것입니다.

---

Open API

API는 서버와 클라이언트를 연결하는 인터페이스라고 하였습니다. 서버에서 제공하는 메서드들을 클라이언트가 이용할 수 있도록 하는 것입니다. 흔히 백엔드 개발자와 프론트엔드 개발자가 서로 협의하여 API를 설계합니다.
Open이라는 의미는 키워드가 붙은 것은 누구에게나 열려 있는 API입니다.('무제한으로 이용가능'이라는 의미는 아닙니다.) 회원가입을 해야하거나 제약사항등을 충족하면 이용할 수 있는 API라는 뜻입니다.

API를 이용하기 위해서는 Key가 필요합니다. Open을 하였으니 회원가입이나 제약사항등을 충족한 사용자에게만 해당 데이터를 제공하기 위함입니다.(서버에서 아무런 조건없이 익명의 클라이언트에게 데이터를 제공할 의무는 없습니다.)

---

Postman

위에서 REST-API에서 언급되었듯이 HTTP API는 여러 데이터들을 일정한 형식에 따라 주고받게 됩니다.
https://www.postman.com/ 에 접속한다음 회원가입, OS에 맞게 다운로드하면 무료로 이용할 수 있습니다.

GET HTTP메서드 사용시 사용되는 쿼리 파라미터도 입력할 수 있습니다.

헤더에 속성을 추가할수 있고

바디에 JSON등 다양한 형식의 내용물들을 입력하여 POST로 전송할 수 있습니다.

GET으로 호출한 데이터의 결과를 확인하는것도 가능합니다.

---

후기

REST-API는 현업에서 중요하게 지켜져야할 규칙인것 같습니다. REST-API를 잘 지키기 위해서는 핵심인 개별 리소스 HTTP URI와 HTTP메서드를 사전에 잘 숙지해서 설계시 좋은 REST-API가 될 수 있도록 해야 할 것 같습니다.

---

GitHub

없음!