개념/기초지식

[HTTP/네트워크] REST API, Open API

칠뎁 2022. 8. 7. 16:15

⭐️ 시작하며

REST API를 이해하기 위해서는 HTTP와 API에 대한 사전 지식이 있어야한다. 

💡 REST API란

 

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

 

REST란?

  • 자원(resource)에 대한 주소를 정하는 방법
  • 디자인 원리/제약, 즉 규칙

 

즉, REST API는 REST 성숙도 모델(RMM,Richardson Maturity Model)을 준수하는 API(애플리케이션 프로그래밍 인터페이스)라고 볼 수 있으며, 그 REST 성숙도 모델에 대해서는 아래에서 설명한다.

 

 

*REST = Representational State Transfer

*로이 필딩의 박사학위 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로써 처음 소개됨

💡 REST API를 잘 적용하기 위한 성숙도 모델(RMM)

 

 

이미지 출처: devopedia

 

 

위의 네가지 REST 성숙도 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다.

그런데 실제로 0~3단계를 모두 지키기가 어렵기때문에 2단계(HTTP메소드 원칙준수)까지만 지켜도 좋은 API 디자인이라고 부르고,

이 경우를 HTTP API라고도 한다.

(실질적으로 완벽하게 다 지킨 REST API가 없으므로 통상적으론 2단계까지만 만족시켜도 RESTful API라고 부름)

 

이제 아래에서 각 단계 하나하나를 뜯어보자!

 

0️⃣ RMM 0단계: POX SWAMP / HTTP 사용

 

이 0단계는 REST API를 위한 기초 단계로, 보통은 전체 어플리케이션을 단 하나의 URI로 노출시킨다.

데이터 패치를 포함한 모든 액션에서 HTTP POST를 이용하며,

*SOAP 이나 *XML-*RPC-based 어플리케이션이 이 레벨에 머문다고 볼 수 있다.

POX 란 Plain Old XML을 말한다. 

 

아마 이 부분에서 아직 배우지 않은 어려운 개념들이 많아서 코드스테이츠에선 'HTTP사용'으로 퉁쳐서 설명했었다.

즉 HTTP로 request와 response를 받으면 0단계는 무조건 통과이다.

 

*SOAP(Simple Object Access Protocol)은 일반적으로 널리 알려진 HTTP, HTTPS, SMTP 등을 통해 XML 기반의 메시지를 컴퓨터 네트워크 상에서 교환하는 프로토콜을 말한다.

 

*XML (eXtensible Markup Language)은 주로 다른 종류의 시스템, 특히 인터넷에 연결된 시스템끼리 데이터를 쉽게 주고 받을 수 있게 하여 HTML(마크업언어)의 한계를 극복할 목적으로  W3C에서 만들어진 마크업 언어를 만들기 위해 사용하는 언어이다.

 

*RPC (Remote Procedure Call) 별도의 원격 제어를 위한 코딩 없이 다른 주소 공간에서 함수나 프로시저를 실행할 수 있게하는 프로세스 간 통신 기술이다. 다시 말해, 원격 프로시저 호출을 이용하면 프로그래머는 함수가 실행 프로그램에 로컬 위치에 있든 원격 위치에 있든 동일한 코드를 이용할 수 있다.

 

요청 내용 요청 응답
블로그 글
목록 확인		 POST /appointment HTTP/1.1
[헤더 생략]

{
  "date":"2022-08-10",
  "doctor":"허준"
}		 HTTP/1.1 200 OK
[헤더 생략]

{
  "slots": [
    {"doctor":"허준","starts":"09:00","end":"12:00"},
    {"doctor":"허준","starts":"14:00","end":"16:00"}
  ]
}
 블로그 글 적기 POST /appointment HTTP/1.1
[헤더 생략]

{
  "doctor":"허준",
  "start":"14:00",
  "end":"15:00",
  "patient":"칠뎁"
}		 HTTP/1.1 200 OK
[헤더 생략]

1️⃣ RMM 1단계: URI / 개별 리소스와의 통신 준수

 

1단계에서는 0단계와 다르게 여러개의 URI를 사용한다. (하지만 여전히 모든 명령에서 HTTP POST만을 사용한다.)

 

모든 리소스는 각각의 유니크한 HTTP URI로 식별된다는 점이 이 1단계의 핵심이다.

따라서 1단계에 따르면 모든 자원은 개별 리소스에 맞는 엔드포인트(요청이 수행되는 곳)를 사용해서 요청하고,

받는 자원에 대한 정보를 응답으로 전달해야 한다.

이렇게 개별 리소스들을 바탕으로한 주소체계를 사용하는 것 역시 API가 RESTful해지기 위한 기초단계이다.

 

  • 엔드포인트를 작성시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양
  • 리소스에 집중해 명사 형태의 단어로 작성

 

추가로 이렇게 URI와 함께 보낸 요청에 대한 응답으로 리소스를 전달할 때도, 사용한 리소스의 정보와 함께, 

리소스에 대한 성공/실패 여부를 반환해야한다.

 

요청 내용 요청 응답
블로그 글
목록 확인		 POST /doctors/허준 HTTP/1.1
[헤더 생략]

{
  "date":"2022-08-10"
}		 HTTP/1.1 200 OK
[헤더 생략]

{
  "slots": [
    {"id":123, "doctor":"허준","starts":"09:00","end":"12:00"},
    {"id":124,  "doctor":"허준","starts":"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": "해당 시간은 이미 예약되어 있습니다"
   }
}

 

⬆️위를 보면 0단계와 다르게 endpoint가 리소스에 특화되서 표현되었다.

행위가 아니라 구체적인 리소스를 명사로 endpoint로 사용하기! 꼭 명심하자

엔드포인트 디자인은..

"언제 어떻게 요청되는가"는 중요하지 않다. (POST /click❌)
"어떤 응답이 제공되는가" & "어떤 리소스의 상태를 변화시키는가"가 중요하다.(POST /slots/123⭕️)

2️⃣ RMM 2단계: HTTP 메소드 원칙 준수

2단계에서는 CRUD에 맞게 적절한 HTTP메서드(GET,POST,PUT,DELETE)를 사용한다.

앞서 0,1단계에선 다양한 HTTP 메서드가 아니라, 오직 POST메서드만을 사용했던 것과 비교된다.

 

아래의 HTTP 메서드 사용의 모범사례를 참고해서 각각의 경우에 딱 맞는 메서드를 사용하여

각각에 맞는 방식으로 요청을 작성하면 된다.

요청 적절한 메소드 주의 및 설명 
조회(Read) GET 서버의 데이터를 변화시키지 않는 요청에 사용해야 함
추가(Create) POST 요청마다 새로운 리소스를 생성
갱신(Update) PUT 또는 PATCH PUT- 교체, 요청마다 같은 리소스를 반환(멱등성 idempotnet)
🛑멱등하지 않은 POST와 구분!

PATCH- 수정
삭제(Delete) DELETE  

 

*멱등성,멱등법칙은 수학이나 전산학에서 연산의 한 성질을 나타내는 것으로, 연산을 여러 번 적용하더라도 결과가 달라지지 않는 성질을 의미한다.

 

요청 내용 요청 응답
블로그 글
목록 확인		 GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1
[헤더 생략]		 HTTP/1.1 200 OK
[헤더 생략]

{
  "slots": [
    {"id":123, "doctor":"허준","starts":"09:00","end":"12:00"},
    {"id":124,  "doctor":"허준","starts":"14:00","end":"16:00"}
  ]
}
 블로그 글 적기 POST /slots/123 HTTP/1.1
[헤더 생략]

{
  "patient":"칠뎁"
}		 HTTP/1.1 201 Created
Location: slots/123/appointment
[헤더 생략]

{
  "appointment": {
      "slot":{"id":"123,"doctor":"허준",...},
      "patient": "칠뎁"
   }
}

보다시피 GET을 쓸 때에는 body없이 query parameter를 적어준다.

 

그밖에 이 단계에서 지켜야할  짜잘한 포인트는 아래와 같다.

  • 응답에 쓰이는 상태코드는 되도록 상세하게 적는다 (200 OK보다는 201 created)
  • 실패할때는 실패한 이유, 성공할땐 성공한 결과값 같이 보내기

3️⃣ RMM 3단계: HATEOAS 원칙 준수

 

 마지막 단계는 HATEOAS(Hypertext As The Engine Of Application State)는 하이퍼미디어 컨트롤을 적용한다.

3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.

이렇게 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트!!

 

응답에 들어가는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.

때문에 클라이언트 개발자들이 응답에 담겨 있는 링크들을 눈여겨본다면, 이 링크들이 조금 더 쉽고, 효율적으로 리소스와 기능에 접근할 수 있게 한다.

 

근데 이게 실질적으로 적기가 쉽지 않아서 실무에선 3단계까지 하지는 않는다고 한다.

요청 내용 요청 응답
블로그 글
목록 확인		 GET /doctors/허준/slots?date=2022-08-10 HTTP/1.1
[헤더 생략]		 HTTP/1.1 200 OK
[헤더 생략]

{
  "slots": [
    {"id":123, "doctor":"허준","starts":"09:00","end":"12:00"},
    {"id":124,  "doctor":"허준","starts":"14:00","end":"16:00"}
  ],

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

⬆️ 위와 같이 허준이라는 의사의 예약 가능 시간을 확인한 후에는

그 시간대에 예약을 할 수 있는 링크를 삽입하거나,

특정 시간에 예약을 완료하고 나서는 그 예약을 다시 확인할 수 있도록 링크를 작성해 넣을 수도 있다.

⭐️ query parameter 과 path parameter

query parameter path parameter
-고차함수 filter쓰듯이 여러개중 여러개 필터링해낼때 사용한다.
-해당되는 조건에 여러 data가 있는 경우 query parmeter를 쓴다.		 -path parameter은 고유한건 하나를 조회해 올때 사용한다.
ex) 하나밖에 없는 ID나 주민등록번호 같은 경우 path parameter/
학생들중 20살 조회 /students?age=20		 ex) 하나밖에 없는 ID나 주민등록번호 같은 경우 path parameter/
학생들중 아이디 chilldev /students?id=chilldev

 

이는 안지킨다고 뭐 큰일나진 않으나, 개발자들끼리의 약속이기도하고 REST API를 지키기 위한 약속이다. 

📌 Open API

 

오픈 API란 개발자라면 누구나 사용할 수 있도록 공개된 API를 말한다.

예 ) 공공데이터 포털, Open Weather Map

 

📌 API Key

 

API key는 서버의 문을 여는 열쇠이다.

API key는 필요한 경우도, 필요하지 않은 경우도 있다.

 

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

📏 REST API에 대한 가이드라인