[Section 2] REST API

PUT vs PATCH

• 전체변경 vs 일부변경
• 멱등성 - 전체를 바꿔주는게
  - 여러번 요청해도 같은 응답을 받는가?
  • 유저 정보가 여러가지(사진, 주소, 아이디)=>patch

멱등성: 연산을 여러 번 적용하더라도 결괏값이 달라지지 않는 성질.

REST API란?

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

REST API 디자인

4단계 모델 (0 ~ 3단계)

REST 성숙도 모델 - 0단계

기본단계, 0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

예약 요청 /appointment로 엔드포인트 사용

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

{
"date":"2023-03-29"
"doctor": "허준"
}

---

REST 성숙도 모델 - 1단계

개별 리소스와의 통신을 준수해야한다. -> REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다. 따라서 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다.

요청하는 리소스에 따라 엔드포인트로 구분

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

{
"date":"2023-03-29"
"doctor": "허준"
}

엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

실패 여부를 포함한 응답을 받아야한다.

HTTP/1.1 409 Conflict
[헤더생략]
{
"appointmentFailure":{
"slot": {"id": 123", "doctor": "허준", ...},
"patient": "김코딩",
"reason": "해당 시간은 이미 예약되어 있습니다."
  }
}

---

REST 성숙도 모델 - 2단계

CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둬야한다. 0,1단계는 CRUD를 고려하지 않고 POST 메서드를 사용

• 조회(Read): 예약 가능 시간 확인,GET메서드로 요청을 보냄
  - 이때 GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달한다.

GET /doctors/허준/slots?date=2022-8-10 HTTP/1.1
[헤더 생략]

• 생성(Create): 특정 시간에 예약, POST메서드로 요청 보냄
  - 응답은 새로 생성된 리소스를 보내주기 때문에 응답 코드는 201 Created로 명확하게 작성해야하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 완벽하게 REST 성숙도 모델의 2단계를 충족한다.
  

요청

POST/slots/123/HTTP/1.1
[헤더 생략]
{
	"patient":"김코딩"
}

응답

HTTP/1.1 201 Created
Location: slots/123/appointment
[헤더생략]
{
"appointmentFailure":{
"slot": {"id": 123", "doctor": "허준", ...},
"patient": "김코딩",
  }
}

• GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.

• POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다.
  매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 따라서 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드POST는 구분하여 사용해야 합니다.

• PUT 메서드와 PATCH 메서드도 구분하여 사용해야 한다. PUT은 교체, PATCH는 수정의 용도로 사용한다.

2단계 까지만 적용되어도 잘 작성된 API라고 한다.

---

REST 성숙도 모델 - 3단계

HATEOAS(Hypermedia As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다. 요청은 2단계와 동일하고 응답에 리소스의 URI를 포함한 링크요소를 삽입한다.

응답

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"
}
}

허준이라는 의사의 예약 가능시간을 확인한 후 링크를 삽입

API 예시

• GET/getUsers => GET/users
  동사가 들어있고, 동어반복

• POST/createUsers=> POST/users
  동사가 들어있고 대문자도 있음

• POST/users/new
  POST /users

• POST/users?sortBy=name

• GET/get_user_info
  언더바 사용x, 동사가 있고, 동어 반복

• GET/users.json
  헤더에 들어갈 수 있는 정보임(확장자 필요 x)

• GET/getUsersByLocation =>location/{locationid}/users
  특정 장소에 있는 유저만 가져오기

Query. parameters

Paging: ?page=1&per_page=30

블로그 API

• 전체 포스팅 목록 가져오기
  - Get/posts
  - 성공 200 ok
  - 실패 400, 401 ,500

• 새글 쓰기
  - POST/posts
  - 바디에 담길 데이터 -> 제목,작성자,내용,날짜...
  - 성공시 201
  - 실패 401,500

• 특정 포스트 삭제
  - DELETE/posts/{postid}

  • 성공 시

• 특정 포스트에 댓글달기
  - POST/posts/{postid}/comment

  • 바디에 들어갈 데이터 -> 작성자, 내용, 날짜...