REST API 이해 및 사용

Twitter 또는 Github와 같은 인터넷의 다른 소스에서 데이터를 가져오는 것에 대해 생각했다면 "REST API"라는 용어를 접했을 가능성이 큽니다. 그러나 REST API는 무엇입니까? 당신을 위해 무엇을 할 수 있습니까? 어떻게 사용합니까?

이 기사에서는 API 문서를 읽고 효과적으로 사용하기 위해 REST API에 대해 알아야 할 모든 것을 배울 것입니다.

REST API란?

YouTube에서 배트맨에 대한 비디오를 찾으려고 한다고 가정해 보겠습니다. Youtube를 열고 검색 필드에 "Batman"을 입력하고 Enter 키를 누르면 배트맨에 대한 비디오 목록이 표시됩니다. REST API도 비슷한 방식으로 작동합니다. 무언가를 검색하면 요청한 서비스에서 결과 목록을 다시 얻습니다.

API 는 응용 프로그래밍 인터페이스입니다. 프로그램이 서로 통신할 수 있도록 하는 일련의 규칙입니다. 개발자는 서버에서 API를 만들고 클라이언트가 API와 통신할 수 있도록 합니다.

REST 는 API의 모양을 결정합니다. "대표 국가 이전"을 의미합니다. 개발자가 API를 만들 때 따르는 규칙 집합입니다. 이러한 규칙 중 하나는 특정 URL에 연결할 때 데이터 조각(리소스라고 함)을 얻을 수 있어야 한다고 명시되어 있습니다.

각 URL을 요청 이라고 하고 사용자에게 다시 전송되는 데이터를 응답 이라고 합니다.

요청의 해부

요청이 4가지 요소로 구성되어 있다는 사실을 아는 것이 중요합니다.

1. 끝점
2. 방법
3. 헤더
4. 데이터(또는 본문)

엔드포인트 (또는 경로)는 요청한 URL입니다. 다음 구조를 따릅니다.

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

root-endpoint 는 요청하는 API의 시작점입니다. Github API의 루트 엔드포인트는 https://api.github.com 이고 루트 엔드포인트 Twitter의 API는 https://api.twitter.com 입니다.

경로 는 요청하는 리소스를 결정합니다. 서비스는 1번, 다른 서비스는 2번, 또 다른 서비스는 3번 등을 요구하는 자동 응답기와 같습니다.

웹사이트의 일부에 링크할 수 있는 것처럼 경로에 액세스할 수 있습니다. 예를 들어, Smashing Magazine에서 "JavaScript" 태그가 지정된 모든 게시물 목록을 얻으려면 https://www.smashingmagazine.com/tag/javascript/ 로 이동합니다. https://www.smashingmagazine.com/ 은 루트 엔드포인트이고 /tag/javascript 는 경로입니다.

어떤 경로를 사용할 수 있는지 이해하려면 API 설명서를 살펴봐야 합니다. 예를 들어 Github의 API를 통해 특정 사용자의 리포지토리 목록을 가져오고 싶다고 가정해 보겠습니다. 문서에서는 다음 경로를 사용하도록 지시합니다.

 /users/:username/repos

경로의 모든 콜론( : )은 변수를 나타냅니다. 이 값을 요청을 보낼 때의 실제 값으로 바꿔야 합니다. 이 경우 :username 을 검색하려는 사용자의 실제 사용자 이름으로 바꿔야 합니다. 내 Github 계정을 검색하는 경우 :username 을 zellwk 로 바꿉니다.

Github에서 내 저장소 목록을 가져오는 끝점은 다음과 같습니다.

 https://api.github.com/users/zellwk/repos

끝점의 마지막 부분은 쿼리 매개변수 입니다. 기술적으로 쿼리 매개변수는 REST 아키텍처의 일부가 아니지만 많은 API에서 이를 사용하는 것을 볼 수 있습니다. 따라서 API를 읽고 사용하는 방법을 완전히 이해하는 데 도움이 되도록 API에 대해서도 이야기하겠습니다. 쿼리 매개변수는 키-값 쌍으로 요청을 수정할 수 있는 옵션을 제공합니다. 항상 물음표( ? )로 시작합니다. 각 매개변수 쌍은 다음과 같이 앰퍼샌드( & )로 구분됩니다.

 ?query1=value1&query2=value2

Github에서 사용자의 리포지토리 목록을 가져오려고 할 때 제공된 결과를 수정하기 위해 세 가지 가능한 매개변수를 요청에 추가합니다.

내가 최근에 푸시한 저장소 목록을 얻으려면 sort 을 push 로 설정할 수 있습니다.

 https://api.github.com/users/zellwk/repos?sort=pushed

이 끝점이 작동하는지 어떻게 알 수 있습니까? 자, 시도해 볼 시간입니다!

curl로 끝점 테스트

모든 프로그래밍 언어로 요청을 보낼 수 있습니다. JavaScript 사용자는 Fetch API 및 jQuery의 Ajax 메서드와 같은 메서드를 사용할 수 있습니다. Ruby 사용자는 Ruby의 Net::HTTP 클래스를 사용할 수 있고 Python 사용자는 Python 요청을 사용할 수 있습니다. 등등.

이 기사에서는 cURL이라는 명령줄 유틸리티를 사용합니다. API 문서는 일반적으로 cURL을 참조하여 작성되기 때문에 cURL을 사용합니다. cURL 사용법을 이해한다면 API 문서를 이해하는 데 문제가 없을 것입니다. 그러면 원하는 언어로 요청을 쉽게 수행할 수 있습니다.

계속하기 전에 컴퓨터에 cURL이 설치되어 있는지 확인해야 합니다. 터미널을 열고 curl -version 을 입력하십시오. 이 명령은 시스템에 설치된 cURL의 버전을 확인합니다.

 curl --version

cURL이 설치되어 있지 않으면 "명령을 찾을 수 없음" 오류가 표시됩니다. 이 오류가 발생하면 계속 진행하기 전에 curl을 설치해야 합니다.

cURL을 사용하려면 curl 다음에 요청하는 엔드포인트를 입력합니다. 예를 들어 Github의 루트 끝점을 가져오려면 다음을 입력합니다.

 curl https://api.github.com

Enter 키를 누르면 Github에서 다음과 같은 응답을 받아야 합니다.

사용자의 리포지토리 목록을 얻으려면 위에서 논의한 것처럼 끝점을 올바른 경로로 수정합니다. 내 저장소 목록을 얻으려면 다음 명령을 사용할 수 있습니다.

 curl https://api.github.com/users/zellwk/repos

cURL과 함께 쿼리 매개변수를 포함하려면 ? 앞에 백슬래시( \ )를 추가해야 합니다. 및 = 문자. 이것 때문에 ? 및 = 는 명령줄의 특수 문자입니다. 명령줄에서 일반 문자로 해석하려면 그 앞에 \ 를 사용해야 합니다.

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

두 명령 중 하나를 사용하여 요청을 수행하십시오! Github의 root-endpont에서 본 것과 유사한 응답을 얻을 수 있습니다(그러나 더 많은 데이터가 있음).

JSON

JSON(JavaScript Object Notation)은 REST API를 통해 데이터를 보내고 요청하기 위한 일반적인 형식입니다. Github에서 다시 보내는 응답도 JSON 형식입니다.

JSON 객체는 JavaScript 객체처럼 보입니다. JSON에서 각 속성과 값은 다음과 같이 큰따옴표로 묶어야 합니다.

 { "property1": "value1", "property2": "value2", "property3": "value3" }

요청의 구조로 돌아가기

요청이 네 부분으로 구성된다는 것을 배웠습니다.

1. 끝점
2. 방법
3. 헤더
4. 데이터(또는 본문)

요청을 구성하는 나머지 부분을 살펴보겠습니다.

방법

메소드는 서버에 보내는 요청 유형입니다. 아래 5가지 유형 중에서 선택할 수 있습니다.

• GET
• POST
• PUT
• PATCH
• DELETE

이러한 메서드는 요청에 대한 의미를 제공합니다. Create , Read , Update 및 Delete (CRUD)의 네 가지 가능한 작업을 수행하는 데 사용됩니다.

API를 통해 각 요청을 사용할 요청 방법을 알 수 있습니다. 예를 들어, 사용자의 저장소 목록을 가져오려면 GET 요청이 필요합니다.

사용자로부터 리포지토리 목록을 가져오려면 GET 요청이 필요합니다. 새 Github 리포지토리를 만들려면 POST 요청이 필요합니다.

-X 또는 --request 뒤에 요청 메서드를 작성하여 cURL에서 요청 메서드를 설정할 수 있습니다. 아래의 이 명령은 cURL을 통해 저장소를 생성하려고 시도합니다.

 curl -X POST https://api.github.com/user/repos

이 요청을 실행해 보십시오. 인증이 필요하다는 응답을 받게 됩니다. (인증에 대한 자세한 내용은 나중에).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

헤더

헤더는 클라이언트와 서버 모두에 정보를 제공하는 데 사용됩니다. 인증 및 본문 내용에 대한 정보 제공 등 다양한 용도로 사용할 수 있습니다. MDN의 HTTP 헤더 참조에서 유효한 헤더 목록을 찾을 수 있습니다.

HTTP 헤더는 콜론으로 구분되는 속성-값 쌍 입니다. 아래 예는 서버에 JSON 콘텐츠를 예상하도록 지시하는 헤더를 보여줍니다.

 "Content-Type: application/json". Missing the opening ".

-H 또는 --header 옵션을 통해 curl과 함께 HTTP 헤더를 보낼 수 있습니다. 위의 헤더를 Github의 API로 보내려면 다음 명령을 사용합니다.

 curl -H "Content-Type: application/json" https://api.github.com

(참고: Content-Type 헤더는 Github의 API가 작동하기 위한 요구 사항이 아닙니다. 이것은 cURL과 함께 헤더를 사용하는 방법을 설명하기 위한 예시일 뿐입니다.)

보낸 헤더를 보려면 다음과 같이 요청을 보낼 때 -v 또는 --verbose 옵션을 사용할 수 있습니다.

 curl -H "Content-Type: application/json" https://api.github.com -v 

여기서 * 는 cURL에서 제공하는 추가 정보를 의미합니다. > 는 요청 헤더를 나타내고 < 는 응답 헤더를 나타냅니다.

데이터(또는 "본문")

데이터("본문" 또는 "메시지"라고도 함)에는 서버에 보내려는 정보가 포함되어 있습니다. 이 옵션은 POST , PUT , PATCH 또는 DELETE 요청에만 사용됩니다.

cURL을 통해 데이터를 보내려면 -d 또는 --data 옵션을 사용할 수 있습니다.

 curl -X POST <URL> -d property1=value1

여러 데이터 필드를 보내려면 여러 -d 옵션을 만들 수 있습니다.

 curl -X POST <URL> -d property1=value1 -d property2=value2

이해가 된다면 요청을 여러 줄로 \ 하여 읽기 쉽게 만들 수 있습니다.

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

서버를 가동하는 방법을 안다면 API를 만들고 자신의 데이터를 테스트할 수 있습니다. 잘 모르지만 시도해 볼 용기가 있다면 이 기사를 따라 Node, Express 및 MongoDB를 사용하여 서버를 만드는 방법을 배울 수 있습니다.

서버를 가동하지 않으려면 Requestbin.com( 무료입니다! )으로 이동하여 "엔드포인트 생성"을 클릭할 수 있습니다. 아래 그림에 표시된 https://requestb.in/1ix963n1 과 같이 요청을 테스트하는 데 사용할 수 있는 URL이 제공됩니다.

요청을 테스트하려면 고유한 요청 저장소를 만들어야 합니다. 요청 저장소는 생성 후 48시간 동안만 열려 있습니다. 이 기사를 읽을 때쯤이면 위에서 만든 휴지통이 사라진지 오래입니다.

이제 일부 데이터를 요청 저장소로 보낸 다음 저장소의 웹페이지를 새로고침해 보십시오. 다음과 같은 데이터가 표시됩니다.

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

기본적으로 cURL은 데이터가 페이지의 "양식 필드"를 통해 전송되는 것처럼 전송합니다. JSON 데이터를 보내려면 Content-Type 을 application/json 으로 설정해야 하고 다음과 같이 데이터 형식을 JSON 객체로 지정해야 합니다.

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

그리고 이것이 (거의!) 요청 구조에 대해 알아야 할 모든 것입니다.

이제 Github의 API를 통해 POST 요청을 보내려고 할 때 "인증 필요"라는 메시지가 표시되는 것을 기억하십니까? 글쎄, 그것은 당신이 POST 요청을 수행할 권한이 없기 때문입니다!

입증

당신의 허락 없이는 누구도 당신의 은행 계좌에 접근하는 것을 허용하지 않을 것입니다. 그렇죠? 같은 생각으로 개발자는 권한이 부여된 경우에만 작업을 수행할 수 있도록 조치를 취합니다. 이렇게 하면 다른 사람들이 귀하를 가장하는 것을 방지할 수 있습니다.

POST , PUT , PATCH 및 DELETE 요청은 데이터베이스를 변경하므로 개발자는 거의 항상 이를 인증 벽 뒤에 둡니다. 어떤 경우에는 GET 요청에도 인증이 필요합니다(예: 현재 잔액을 확인하기 위해 은행 계좌에 액세스할 때).

웹에서 자신을 인증하는 두 가지 주요 방법이 있습니다.

1. 사용자 이름 및 암호 사용(기본 인증이라고도 함)
2. 비밀 토큰으로

비밀 토큰 방식에는 Github, Google, Twitter, Facebook 등과 같은 소셜 미디어 네트워크에서 자신을 인증할 수 있는 oAuth가 포함됩니다.

이 기사에서는 사용자 이름과 비밀번호로 기본 인증을 사용하는 방법만 배우게 됩니다. oAuth로 인증하는 데 관심이 있다면 Zack Grossbart의 "OAuth2 및 Facebook으로 로그인에 대해 알아야 할 사항"을 읽는 것이 좋습니다.

cURL을 사용하여 기본 인증을 수행하려면 다음과 같이 -u 옵션을 사용하고 사용자 이름과 암호를 사용할 수 있습니다.

 curl -x POST -u "username:password" https://api.github.com/user/repos

위의 요청에서 사용자 이름과 비밀번호로 자신을 인증해 보세요. 인증에 성공하면 "인증 필요"에서 "JSON 구문 분석 문제"로 응답이 변경되는 것을 볼 수 있습니다.

이는 아직 모든 POST , PUT , PATCH 및 DELETE 요청에 필요한 데이터를 서버에 제공하지 않았기 때문입니다.

지금까지 배운 지식으로 위의 코드를 편집하여 cURL을 통해 Github 저장소를 만들 수 있어야 합니다. 나는 당신이 그것을 스스로 시도하도록 놔둘 것입니다!

이제 HTTP 상태 코드와 오류 메시지에 대해 이야기해 보겠습니다.

HTTP 상태 코드 및 오류 메시지

"인증 필요" 및 "JSON 구문 분석 문제"와 같은 이전에 받은 메시지 중 일부는 오류 메시지입니다. 요청에 문제가 있는 경우에만 나타납니다. HTTP 상태 코드를 사용하면 응답 상태를 빠르게 알 수 있습니다. 범위는 100+에서 500+입니다. 일반적으로 숫자는 다음 규칙을 따릅니다.

1. 200+ 는 요청이 성공 했음을 의미합니다.
2. 300+ 는 요청이 다른 URL로 리디렉션 됨을 의미합니다.
3. 400+ 는 클라이언트에서 발생한 오류가 발생했음을 의미합니다.
4. 500+ 는 서버에서 발생한 오류가 발생했음을 의미합니다.

자세한 정보 표시 옵션( -v 또는 --verbose ) 또는 헤드 옵션( -I 또는 --head )을 사용하여 응답 상태를 디버그할 수 있습니다.

예를 들어 사용자 이름과 암호를 제공하지 않고 POST 요청에 -I 를 추가하려고 하면 401 상태 코드(Unauthorized)가 표시됩니다.

데이터가 잘못되었거나 누락되어 요청이 유효하지 않은 경우 일반적으로 400 상태 코드(잘못된 요청)를 받습니다.

특정 HTTP 상태 코드에 대한 자세한 정보를 얻으려면 MDN의 HTTP 상태 참조를 참조하십시오.

API 버전

개발자는 수시로 API를 업데이트합니다. 때때로 API가 너무 많이 변경되어 개발자가 API를 다른 버전으로 업그레이드하기로 결정할 수 있습니다. 이런 일이 발생하여 애플리케이션이 중단되는 경우 일반적으로 이전 API에 대한 코드를 작성했지만 요청이 최신 API를 가리켰기 때문입니다.

두 가지 방법으로 특정 API 버전을 요청할 수 있습니다. 선택하는 방법은 API 작성 방법에 따라 다릅니다.

이 두 가지 방법은 다음과 같습니다.

1. 엔드포인트에서 직접
2. 요청 헤더에서

예를 들어 Twitter는 첫 번째 방법을 사용합니다. 작성 당시 Twitter의 API는 버전 1.1이며 엔드포인트를 통해 알 수 있습니다.

 https://api.twitter.com/1.1/account/settings.json

반면 Github은 두 번째 방법을 사용합니다. 작성 당시 Github의 API는 버전 3이며 Accept 헤더로 버전을 지정할 수 있습니다.

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

마무리

이 기사에서는 REST API가 무엇이고 cURL을 사용하여 GET , POST , PUT , PATCH 및 DELETE 메소드로 요청을 수행하는 방법을 배웠습니다. 또한 -u 옵션을 사용하여 요청을 인증하는 방법과 HTTP 상태의 의미도 배웠습니다.

이 기사가 REST API에 대해 충분히 배우고 애플리케이션을 만들 때 유창하게 사용할 수 있기를 바랍니다. 궁금한 사항이 있으면 언제든지 내 블로그를 방문하거나 아래에 의견을 남겨주세요.