📖 RESTful API

🧑🏼‍🚀 알아야 하는 이유

❗웹서버로 자원 요청을 어떤 경로로 하는지 알고 싶다면

🙋🏻‍♂️ 이 문서를 보고 나면

• 클라이언트에서 웹서버로 자원을 요청 하는 가이드라인을 알 수 있다.

RESTful API

2010년도쯤부터 Mashup (opens new window)이라는 단어가 많이 사용됐습니다. 구글 지도를 비롯한 클라이언트에서 처리할 수 없는 대용량 데이터, 날씨 정보 등 관측 시스템에서 보내는 실시간 정보를 취급하는 웹서비스들이 많이 만들어졌는데요. 이러한 서비스는 웹 브라우저에서 사용하는 것을 전제로 만들어졌지만, API도 제공하고 있어 웹 서비스를 조합해 사용할 수도 있습니다. 웹 서비스를 결합해 새로운 부가가치를 창출하는 방법을 '매시업'이라고 합니다. 이렇게 웹 서비스의 인터페이스로서 HTTP를 기반으로 한 서버/클라이언트 간 통신이 널리 이용되었습니다.

REST(Representational State Transfer)는 미국 컴퓨터 과학자 Roy Thomas Fielding이 2000년에 네트워크를 기반으로 하는 소프트웨어 아키텍처 논문에서 발표한 것입니다. 그는 HTTP 책정에도 관여했고, 아파치 웹 서버 프로젝트의 공동 설립자 중 한 사람이기도 합니다. REST는 매시업이 활발하게 이루어지게 되고, 웹이 브라우저에서 웹 애플리케이션 간의 연계를 위한 것으로 용도가 넓어지면서 알려지고 사용되기 시작했습니다. 구글의 디자인 가이드 (opens new window)에 따르면 2010년에는 전 세계의 네트워크를 통해 공개된 API의 74%가 REST API로 되어 있습니다.

REST는 HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미합니다. 대략적으로 아래의 특성이 있습니다.

• API가 웹 서버를 통해 제공된다.
• GET/users/[사용자 id]/repositories처럼 경로에 메서드를 보내 서비스를 얻는다.
• API가 성공했는지 status code로 클라이언트에 알려준다.
• URL은 리소스의 위치를 나타낸다.
• 필요에 따라 GET 매개변수, POST의 바디 등 추가 정보를 보낼 수도 있다.
• 서버에서 오는 반환 값으로는 JSON 또는 XML과 같은 구조와 텍스트나 이미지 데이터 등이 반환되는 경우가 많다.

클라이언트 관점에서는 서버에 다음과 같은 것을 기대할 수 있습니다.

• URL은 리소스의 계층을 나타낸 경로로 되어 있다. 명사로만 구성된다.
• 리소스에 대해 HTTP 메서드를 보내 리소스 취득, 갱신, 추가 등의 작업을 한다.
• status code를 보고 요청이 제대로 처리됐는지 판정할 수 있다.
• GET 메서드는 여러번 호출해도 상태를 변경하지 않는다.
• 클라이언트 쪽에서 관리해야 할 상태가 존재하지 않고, 매번 요청을 독립적으로 발행할 수 있다.

이러한 REST 원칙들을 준수한 것을 RESTful이라고 표현합니다.

Github REST API

다양한 서비스들에서 API를 제공하는데 우리는 Github API (opens new window)를 살펴보겠습니다. Github API의 경우 공개 정보라면 로그인과 사용자 인증이 필요하지 않기 때문인데요. 간단하게 아래의 항목들을 Postman (opens new window)을 통해 직접 조회해보도록 하겠습니다. Postman (opens new window)은 실제 웹페이지에 REST API를 요청하는 코드를 작성하지 않아도, API 명세만 알고 있다면 요청을 하고 응답하는 과정들을 확인해볼 수 있게 도와주는 도구입니다.

• Github에서 자신의 공개 프로필 정보
• 자동차 경주 게임 미션의 PR 정보 리스트 가져오기
• woowacourse organization에 대한 정보 가져오기

📘 정리

• REST는 URI를 통해 자원을 명시한다
• 클라이언트는 status code를 통해 API의 성공 여부를 알 수 있다.
• 서버에서 제공하는 데이터는 주로 JSON 형태의 데이터이다.

🔗 참고 링크

• MDN_REST (opens new window)
• Postman (opens new window)
• Github_API_docs (opens new window)