[TIL] Unit 8. REST API

string_main·2022년 6월 10일
0

Network

목록 보기
1/1
post-thumbnail

🌱 REST API


  • 정의 : REST API는 웹에서 사용되는 데이터(data)나 자원(Resource)을 HTTP URI로 표현하고 HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다.

    • REST는 Representational State Transfer의 약자로 로이 필딩의 논문에서 HTTP의 장점을 최대한 활용할 수 있는 아키텍처로 처음 소개되었다.

식당에 갔는데 메뉴판이 이렇다면... 매우 보기 불편하고 주문하기도 어려울 것이다.

➡️ 알아보기 쉽고 잘 작성된 메뉴판이 필요하다!

🌱 REST API 디자인 방법


  • Richardson 성숙도 모델(RMM) : 총 0~3단계로 나누어지며 로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했지만, 실제로 3단계까지 지키기 어려워서 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있으며, 이를 HTTP API라고도 부른다.

🌿 REST 성숙도 모델 : 0단계

  • 단순히 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
[헤더 생략]

🌿 REST 성숙도 모델 : 1단계

  • 개별 리소스(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" : "해당 시간은 이미 예약 마감 되었습니다."
     }
}

🌿 REST 성숙도 모델 : 2단계 (HTTP API)

  • 앞선 단계에서는 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단계 충족)
  • 주의 사항 :
    • GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 함.
    • POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환함. (이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 하며, 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용해야 함)
    • PUT 메서드와 PATCH 메서드도 구분하여 사용해야 한다. PUT은 교체, PATCH는 수정의 용도로 사용한다.

🌿 REST 성숙도 모델 : 3단계

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

🌱 Open API


  • 정의 : 누구에게나 열려있는 API로, 정부에서 제공하는 공공데이터가 그 예시이다.

    • API마다 정해진 이용 수칙(가격, 정보의 제한, 호출 횟수 제한 등)이 있다.
  • 예시 :

  • API Key : API를 이용하기 위해 필요한 서버의 문을 여는 열쇠. (가끔 API key가 필요하지 않은 경우도 있긴 함)

    • 로그인한 이용자에게 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있다.

🌱 HTTP API 테스트 도구


  • 웹 개발에서 사용하는 대표적인 클라이언트는 브라우저이다. 이는 서버에 HTTP 요청을 보낼 수 있는 훌륭한 도구이지만, 주로 웹 페이지를 받아오는 GET 요청에 사용한다. (브라우저의 주소창에 URL을 입력하면, 해당 URL의 root-endpoint로 GET 요청을 보냄)
  • 테스트를 위해 GET 요청이 아닌 다른 요청을 보내려면, 개발자 도구의 콘솔 창에서 Web API fetch를 사용해야 한다.
  • 그렇지만, 테스트를 위해 매번 코드를 작성하는 것은 상당히 번거로운 작업이다. HTTP 요청을 테스트할 수 있는 다양한 API 테스트 도구가 존재한다!

🌱 Postman


  • Postman : API 개발을 보다 빠르고 쉽게 구현할 수 있도록 도와주고, 개발된 API를 테스트하여 문서화 및 공유할 수 있도록 도와주는 플랫폼

  • 실습 :

  1. API > Current Weather Data > API Doc > By city ID
  2. 주어진 URI와 발급받은 API key로 날씨 데이터에 접근할 수 있다.
  3. 브라우저에 URI를 입력한다.
// 주어진 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}
  1. JSON 형태의 데이터를 확인할 수 있다. (크롬 확장 프로그램 JSON Viewer를 적용하면 보기 편하다.)

🌱 Check List


  • REST API에 대해 이해할 수 있다.
  • REST 성숙도 모델에 대해 이해할 수 있다.
  • REST API 문서를 읽을 수 있다.
  • REST API에 맞춰 디자인할 수 있다.
  • Open API와 API Key에 대해 이해할 수 있다.
  • Postman을 사용하는 방법에 대해 이해할 수 있다.
  • Postman으로 API를 테스트 할 수 있다.
  • Postman으로 날씨를 받아올 수 있다.

🌱 추가 학습


  • REST API 직접 디자인해보기
  • 디자인한 데이터 모델을 Strapi를 이용하여 구현하기

| 참고자료 |

  • CodeStates - UrClass
profile
FE developer

0개의 댓글