6.25 Dev.Feedback (REST API)

Rest API ( Representational State Transfer)

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

REST API는 웹에서 사용되는 모든 자원을 HTTP URI로 표현하고, HTTP Method를 통해 요청과 응답을 정의하는 방식을 말한다.

REST API를 사용하려면 REST 아키텍처의 제약 조건을 준수해야 한다.

 

Endpoint

root-endpoint(혹은 root-URL)  : API로 서버와 통신할 때, 서버가 요청을 수락하는 시작점을 뜻한다. 혹은 API가 시작되는 지점이라고 생각하면 이해가 편하다.

 

Github API의 root-endpoint는 https://api.github.com이고, 트위터 API의 root-endpoint는 https://api.twitter.com다.

 

path: path(또는 url-path)는 API를 통해 서버와 통신할 때, 서버와 통신할 수 있는 key 역할을 한다. 서버에 정의된 문자열에 따라 path가 달라진다. 예를 들어, https://api.github.com/user 에서는 'user'가 path입니다. 즉 path를 통해 내가 원하는 리소스를 가져올 수 있는 것이다.

 

 

네이버 웹툰 사이트를 예시로 들어보면, comic.naver.com/ 여기가 root-endpoint, /webtoon/weekday.nhn이 path이다.

메시지 조회

Request

GET /{githubID}/messages

githubID가 작성한 모든 메시지를 조회합니다.

이 요청에는 추가적인 파라미터(query parameter)를 사용할 수 있다. 파라미터는 다음과 같이 사용할 수 있다.

GET /{githubID}/messages?roomname=lobby

여기서 질문 / 파라미터는 어떤 식으로 정해지는 가? 형식은 어떤 종류가 있는가? 설명과 필수 포함여부는 어떻게 확인할 수 있는가?

 

Response

응답은 JSON 형식으로 온다.

[
  {
    "id": 1,
    "username": "happydrum819",
    "text": "Lovely Cat",
    "roomname": "lobby",
    "date": "2021-07-28T03:54:21.134"
  },
  // ...여러 개의 메시지
]

메세지에서 사용하는 파라미터의 정보들

메시지 추가

Request

POST /{githubID}/messages

{githubID} 부분은, 각 개인의 아이디를 넣으면 된다. 메시지는 24시간마다 자동으로 리셋된다.

 

요청 본문엔 다음 내용을 반드시 포함해야 한다.

• 요청 형식: JSON
  • MIME 타입: application/json

MIME 타입은 무엇인가?

예시를 통해서 보고 싶다. 어떤식으로 넣어야지? 아래 링크를 보며, 공부를 더 해보자. 

https://developers.kakao.com/docs/latest/ko/message/rest-api

 

Response

역시 응답은 JSON 형식으로 온다.

{
  "id": 5
}

아이디가 숫자형식으로 오는데, 이 말은 우리가 포스트한 메세지에 5번이라는 고유한 아이디가 부여되어있다는 뜻이다.

 

메시지 초기화

Request

메세지 초기화에는 따로 요청 본문이 필요하지 않다.

POST /{githubID}/clear

Response

역시 응답은 JSON으로

{
  "message": "message initialized!"
}

REST API는 어떻게 디자인해야 하는가

REST API는 공식적으로 정해진 뚜렷한 규격이 없이 뚜렷한 특징만이 눈에 보인다. 그래서 개발자들은 그 뚜렷한 특징을 기반으로 삼아 다양한 형식의 코딩을 진행하고 있다. 하지만, 꾸준하게 모범 사례들을 모아 논의하고 통합하고 있기에 미리 찾아보고 학습해볼만한 좋은 디자인들이 있다.

• 5가지의 기본적인 REST API 디자인 가이드
• 호주 정부 API 작성 가이드
• 미국 백악관 API 작성 가이드
• 구글 API 작성 가이드

API 작성 가이드를 모두 읽었다면, REST API 설계시 가장 중요한 두 가지를 이해할 수 있다.

• URI는 정보의 자원을 표현한다.
• 자원에 대한 상태 정의는 HTTP method(GET, POST, PUT, DELETE...)로 표현한다.

예를 들어, GET /user/1122/post라는 URI는 REST API에 부합하지 않는다.

POST /user/1122처럼 표현하는 것이 REST API 규칙에 부합한다.

Open API와 API Key

Open API

• 정부에서 제공하는 공공데이터가 있다.
• 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있다.
• 공공데이터포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있다.
• 이 외에도 네이버 지도, 구글맵, 메타블로그 역시 Open API 기반으로 서비스가 제공되고 있다.

 

이 API에는 "Open"이라는 키워드가 붙어 있다. 글자 그대로 누구에게나 열려있는 API이다. 그러나 "무제한으로 이용할 수 있다"는 의미는 아니다. 기관이나 API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.

 

하나의 예시로는 오픈스트리트 맵이 있다.

https://www.openstreetmap.org/#map=6/35.948/127.736

 

오픈 스트리트맵의 오픈API는 무료이지만 구글은 단계적인 유료화를 통해 2018년 구글 맵스 API를 무료사용권 제도를 사용한 전면 유료화 방침을 확정했다.이처럼 공개된 오픈API일지라도 데이타 사용 용량에 따라 비용을 지불해야 하는 경우가 있거나 완전히 무료일지라도 사용자가 회원가입을 통한 신원확인후 서비스제공자로부터 공개키(또는 사용권한 토큰)을 별도로 발급받아 오픈API를 사용토록 장려함으로서 무분별한 데이터 남용을 막는 사례가 늘고 있다.

 

Open API를 간단하게 경험해 볼 수 있는 대표적인 페이지는, Open Weather Map이라는 웹 사이트에서 제공하는 날씨 API도 있다. 이 웹사이트에서는 다음의 설명처럼 데이터를 제공한다.

• 제한적이나마 무료로 날씨 API를 사용할 수 있다.
  • 프리 플랜에서는 기본적으로 분당 60번, 달마다 1백 번 호출이 가능하다.
• 데이터를 JSON 형태로 응답한다.

API Key

API를 이용하기 위해서는 API Key가 필요하다. API key는 서버의 문을 여는 열쇠라고 생각할 수 있다. 클라이언트의 요청에 따라 서버에서 응답한다는 말은 결국 서버를 운용하는 데에 비용이 발생한다는 말이다. 따라서 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무도, 이유도 없다.

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

 

HTTP 헤더에 Authorization 정보를 추가하여 인증 받을 수 있다. API를 요청한 계정의 소유자를 확인하는데 필수적인 절차로 여겨진다.

 

 간단하게 말하면 API Key는 개발자들이 기존의 암호를가지고 사용자를 인증하는 복잡한 과정없이 사용자의 Identity를 확인하고 싶어서 만든 방식이다.  누가 우리 시스템에 접근하는지 그리고, 얼마나 API를 사용하는지 식별할 수 있는 편리한 방법이며, 심지어, API Key 별로 호출량을 통제할 수도 있다.

 

질문 // 가끔 API key가 필요하지 않은 경우도 있다고 하는데, 그 경우는 어떤 경우인가?