[네트워크]REST API(feat. Open API, API Key)

 

REST API

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

 

 

 좋은 REST API를 디자인하는 방법

  레오나르드 리차드슨의 REST 성숙도 모델

• 0단계
  • 단순히 HTTP프로토콜을 사용하기만 해도 된다. 해당 API는 REST API라고 할 수 없으며, 0단계는 좋은 REST API를 작성하기 위한 기본 단계이다.
• 1단계
  • 개별 리소스와의 통신을 준수해야한다.
  • 모든 자원은 개별 리소스에 맞는 엔드포인트를 사용해야 한다.
  • 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다.
  • 엔드포인트 작성 시 동사, HTTP 메서드 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.
  • 요청에 따른 응답으로 리소스를 전달할 때도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야한다.
• 2단계
  • CRUD에 맞게 적절한 HTTP메서드를 사용하는 것에 중점을 둔다. 
  • 예약 가능한 시간을 확인 = 조회하는 행위로 GET 메서드 사용, 특정 시간에 예약 = 예약 생성으로 POST 메서드 사용
  • 응답이 어떻게 반환되는지도 중요하다. 예로 POST요청에 대한 응답일 경우 새롭게 생성된 리소스를 보내주기 때문에 응답코드도 201 created로 명확하게 작성해야하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 해야 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 볼 수 있다.
• 3단계
  
  • 3단계 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성한다는 것이 다르다.
  • 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있습니다.

 참고 API 가이드

• 5가지의 기본적인 REST API 디자인 가이드
• 구글 API 작성 가이드
• MS의 REST API 가이드라인

 

 Open API

  글자 그대로 누구에게나 열려있는 API이다. 

• 기관이나 API마다 정해진 이용수칙이다.
• 참고 Open API
  • 공공데이터 포털
  • 날씨 API

 

 API Key

 API를 이용하기 위해서는 API Key가 필요하다. 서버 입장에 아무런 조건없이 익명의 클라이언트에게 데이터를 제공할 의무도 이유도 없다. 그래서 로그인된 이용자에게만 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API Key를 같이 전달해야만 원하는 응답을 받을 수 있다.