REST API란?
-
Representational State Transfer의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 것을 의미
-
HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미
CRUD란?
-
대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인 CREATE (생성), READ (조회), UPDATE (수정), DELETE (삭제)를 묶어서 일컫는 말
-
CREATE
- 데이터 생성 (POST)
-
READ
- 데이터 조회 (GET)
-
UPDATE
- 데이터 수정 (PUT, PATCH)
-
DELETE
- 데이터 삭제 (DELETE)
REST API 성숙도 모델
리차드슨의 REST 성숙도 모델을 구조화하면 다음과 같으며 실제로는 3단계까지 전부 지키기는 힘드므로 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있다고 한다. 이러한 경우를 HTTP API라고도 부른다.
REST 모델 - 0단계
- HTTP 프로토콜을 사용하기만 해도 된다.
REST API는 아니지만 좋은 REST API를 작성하기 위한 기본 단계이다.
예약 가능한 시간 확인
요청
POST /appointment HTTP/1.1
{
"date": "2023-02-05"
"doctor": "허준"
}
응답
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 /appointment HTTP/1.1
{
"doctor": "허준",
"start": "14:00",
"end" : "15:00",
"patient": "홍길동"
}
응답
HTTP/1.1 200 OKREST 모델 - 1단계
-
개별 리소스와의 통신을 준수해야 함
- 요청하는 리소스에 따라 다른 엔드포인트 사용
개별 리소스에 맞는 엔드포인트를 사용해야 한다는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다. 또한 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.
- 엔드포인트 작성 요령
동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중하여 명사 형태로 작성하는 것이 바람직
예약 가능한 시간 확인
요청
POST /doctors/허준 HTTP/1.1
{
"date": "2023-02-05"
"doctor": "허준"
}
응답
HTTP/1.1 200 OK
{
"slots": [
{ "id": 123, "doctor": "허준", "start": "09:00", "end": "12:00" },
{ "id": 124, "doctor": "허준", "start": "14:00", "end": "16:00" }
]
}- 요청의 엔드포인트로
/doctors/허준사용 - 응답으로는 의사 허준의 예약 가능한 시간대가 반환
특정 시간에 예약
요청
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": "이미 예약되어 있는 시간대입니다."
}
}
- 요청의 엔드포인트로
/slots/123사용 - 응답으로 실패 여부를 포함하여 반환
REST 모델 - 2단계
-
응답 코드가 명확해야 하며, 관련 리소스를 클라이언트가 헤더에 작성된 URI를 통해 확인할 수 있어야 함
-
CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것이 중요
HTTP 메서드인 GET, POST, PUT, DELETE를 사용하여 CRUD를 나타내야 함
예약 가능한 시간 확인
요청
GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1
응답
HTTP/1.1 200 OK
{
"slots": [
{ "id": 123, "doctor": "허준", ...},
{ "id": 124, "doctor": "허준", ...}
]
}-
확인을 하는 것은 조회를 의미하며, 조회를 위한
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": "홍길동"
}
}-
예약을 하는 것은 예약을 생성하는 것을 의미하며, 생성을 위한
POST메서드를 사용 -
새로운 리소스를 응답으로 보내주기 때문에
201 Created와 같은 응답 코드로 명확하게 작성하여야 하며 관련 리소스를 클라이언트가Location헤더에 작성된 URI를 통해 확인할 수 있도록 해야 함
REST 모델 - 3단계
-
HATEOAS(Hypertext As The Engine Of Application State)라는 하이퍼 미디어 컨트롤을 적용
-
요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성
링크 요소에는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼 미디어 컨트롤을 포함
예약 가능한 시간 확인
요청
GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1
응답
HTTP/1.1 200 OK
{
"slots": [
{ "id": 123, "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",
"method": "GET"
}
}
}- 응답으로 예약을 완료하고 해당 예약을 다시 확인할 수 있도록 하는 링크를 작성할 수 있음
REST 성숙도 모델 요약
-
CRUD 잘 지키기
-
개별 리소스에 필요한 적절한 명사로 엔트포인트 구성
-
응답 코드 명확하게 작성
-
요청으로 리소스 사용에 대한 성공/실패 여부 반환하기
-
응답에 하이퍼 미디어 컨트롤 적용하기
