REST API

끝없는 공부 ....

싫어요 ..

---

REST API

REST ?

: Representational State Transfer의 약자

• 자원(리소스)을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것
• 자원의 표현에 대한 상태 전달
  • 자원의 표현 : 학생정보 ➡️ Students
  • 자원의 상태 전달 : JSON, XML을 통해 주고받는 것이 일반적

REST API ?

: REST 기반으로 서비스 API를 구현한 것

• API : 데이터와 기능의 메뉴판을 제공하여 컴퓨터 프로그램 간 상호작용 촉진, 서로 정보를 교환할 수 있도록 하는 것
• 웹에서 사용되는 데이터, 리소스를 HTTP URI로 표현하고, HTTP Method (POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD를 적용하는 것

• HTTP 프로토콜을 이용해 API를 설계하기 위한 아키텍처(메뉴판 설계) 스타일
• 서버에서 직접 웹 어플리케이션, 사이트의 사용자에게 데이터를 제공해야 하는 모든 곳에서 REST API를 사용
• REST API의 주요 구성요소
  • 표현 ( Representation ) : Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답을 보낸다.
    ➡️REST에서 하나의 자원은 JSON, XML 등 여러 형태의 응답 으로 나타내어 질 수 있음
  • 행위 ( verb ): HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다.
  • 자원 ( Resource ) : 서버가 클라이언트에 전송해주는 모든 데이터

---

REST API 성숙도 모델

✓ 0단계

➡️ HTTP프로토콜을 사용하기만 하면 OK

요청 : POST/appointment HTTP/ 1.1 
	  {...}
응답 : HTTP/1.1 200 OK

but ) 0단계만 사용하는 경우 REST API라고 할 수 없다 ❌

✓ REST 1단계

➡️ 개별 리소스와 통신을 준수해야한다.

• 개별 리소스에 맞는 엔드포인트 (Endpoint) 사용
• 0 단계에서는 엔드포인트로 /appointment 사용
  ➡️ 1단계에서는 요청하는 리소스에 따라 엔드포인트 구분하여 사용 !
• 엔드포인트 (EndPoint) 작성법

  • 리소스에 집중해 명사형태의 단어로 작성
  • 동사, HTTP 메소드, 행위에 대한 단어 사용은 지양

• 요청받은 자원에 대한 정보 ➡️ 응답으로 전달
  • 사용한 리소스에 대한 정보와 함께 사용에 대한 성공/실패 여부를 반환해야함 ( 예약 성공했나요? )

Example

• 요청 : 허준이라는 의사의 3/30일 예약 가능시간 언제 돼?

POST /doctors /허준 /HTTP/1.1
     { 
       "data" : "2023-03-30" 
     }
     

• 🖥️ 응답 : 이 시간에 예약 가능해

HTTP/1.1 200 OK
  "slots" : [
     {"id":123, "doctor": "허준" ~}
   ]

• 요청 : 그럼 나 이시간에 김코딩으로 예약해줘

POST /slots/123 HTTP/1.1
{
   "patient" : "김코딩"
}

• 예약이 성공한 경우 ( 🖥️ 예약 됐어 )

HTTP/1.1 200 OK

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

• 예약이 실패한 경우 ( 🖥️ 이미 예약자가 있어 )

HTTP/1.1 409 ConFlict

➡️ 409는 Conflict.
: 이 응답은 요청이 현재 서버의 상태와 충돌될 때 나오는 에러코드 ( 4: 내잘못, 5: 니잘못 )

• 참고

  • 1xx : 전송 프로토콜 수준의 정보 교환
  • 2xx : 클라어인트 요청이 성공적으로 수행됨
  • 3xx : 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
  • 4xx : 클라이언트의 잘못된 요청
  • 5xx : 서버쪽 오류로 인한 상태코드

✓ REST 2단계

: 4가지 HTTP Method를 사용해서 CRUD 표현

• 이전 단계에서는 모든 요청을 POST 메서드를 사용함
• 2단계 이전 예시들은 REST 성숙도 2단계에 따르면 CRUD에 따른 적합한 메서드를 사용한 것이 아님..
• 예약 가능시간 조회 : 시간을 조회 ( READ ) 하는 행위 ➡️ GET
  • 이때 GET 메서드는 body를 가지지 않음 ➡️ query parameter 사용
• 특정 시간에 예약 : 예약을 생성 ( CREATE ) 하는 행위 ➡️ POST
  • 이때 POST요청에 대한 응답 또한 중요
    ➡️ 새롭게 생성된 리소스를 보내줌 (예약 잘 됐어) ➡️ 📌 응답코드 201 Created 로 명확하게 작성
  • 이와 관련된 리소스를 클라이언트가 Location 헤더에 작성 된 URI를 통해 확인할 수 있어야함 !
    

여기까지만 만족해도 좋은 API 디자인 👍🏻

✓ REST 3단계

: HATEOAS 하이퍼 미디어 컨드롤 (Hypertext As The Engine Of Application State)을 적용

• 2단계와 거의 동일하나, 응답에는 리소스의 URI를 포함한 링크를 넣어 새로운 기능에 접근할 수 있도록 함!
  ➡️ 이때 응답에 들어가는 리소스 링크요소는 응답을 받은 뒤 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있음
  ex. 예약 가능 시간 응답 ➡️ 그 시간대에 예약할 수 있는 링크 삽입

• 요청 ( 22/8/10일 언제 예약 돼 ? )
  

• 응답 ( links ➡️ 예약사이트 제공 )
  

  ex. 특정시간 예약 완료 ➡️ 예약 여부 확인 가능 링크 삽입