REST API 시작

이 문서의 예제에서는 https://api.github.com에 요청을 보냅니다. 다른 도메인인 octocorp.ghe.com 에서 GitHub에 액세스하는 경우, API 요청의 엔드포인트는 해당 도메인을 반영합니다. 예: https://api.octocorp.ghe.com/.

기본적으로 curl은(는) 유효한 User-Agent 헤더를 보냅니다. 그러나 GitHub 헤더 값에 사용자 GitHub 이름 또는 애플리케이션 User-Agent 이름을 사용하는 것이 좋습니다. 이렇게 하면 문제가 있는 경우 GitHub가(이) 연락할 수 있습니다.

요청을 인증하려면 필요한 범위 또는 권한이 포함된 인증 토큰을 제공해야 합니다. 토큰을 얻는 몇 가지 방법이 있습니다: personal access token을(를) 생성하거나, GitHub App로 토큰을 생성하거나, GitHub Actions 워크플로에서 내장된 GITHUB_TOKEN을(를) 사용할 수 있습니다. 자세한 내용은 REST API에 인증을(를) 참조하세요.

인증 토큰을 사용하는 요청의 예는 요청하기를 참조하세요.

이 섹션에서는 .를 사용하여 GitHubREST API에 curl 인증된 요청을 만드는 방법을 보여 줍니다.

1. 설정

해당 머신에 curl이 설치되어 있어야 합니다. curl이 설치되어 있는지 확인하려면 명령줄에서 curl --version을 실행합니다.

•         `curl` 버전에 대한 정보가 출력되면 `curl`이(가) 설치된 것입니다.
  

•         `command not found: curl`과 유사한 메시지가 표시된느 경우 `curl`이 설치되지 않은 것입니다. 
          `curl`을 다운로드하여 설치합니다. 자세한 내용은 [cURL 다운로드 페이지](https://curl.se/download.html)를 참조하세요.
  

2. 요청에 대한 엔드포인트 선택

1. 요청할 엔드포인트를 선택합니다. GitHub의 REST API 설명서를 탐색하여 GitHub와 상호 작용할 수 있는 엔드포인트를 발견할 수 있습니다.

2. 엔드포인트의 HTTP 메서드 및 경로를 식별합니다. 요청과 함께 이러한 것들을 보냅니다. 자세한 내용은 HTTP 메서드 및 경로를 참조하세요.

   예를 들어 "문제 만들기" 엔드포인트는 HTTP 메서드 POST 및 /repos/{owner}/{repo}/issues 경로를 사용합니다.

3. 필요한 경로 매개 변수를 식별합니다. 필수 경로 매개 변수는 엔드포인트의 경로에 중괄호 {}로 표시됩니다. 각 매개 변수 자리 표시자를 원하는 값으로 바꿉니다. 자세한 내용은 경로를 참조하세요.

   예를 들어 "문제 만들기" 엔드포인트는 /repos/{owner}/{repo}/issues 경로를 사용하며 경로 매개 변수는 {owner} 및 {repo}입니다. API 요청에서 이 경로를 사용하려면 {repo}을(를) 새 문제를 만들 리포지토리의 이름으로 바꾸고 {owner}을(를) 리포지토리를 소유한 계정의 이름으로 바꿉니다.

3. 인증 자격 증명 만들기

요청을 인증할 액세스 토큰을 만듭니다. 토큰을 저장하여 여러 요청에 사용할 수 있습니다. 토큰에 엔드포인트에 액세스하는 데 필요한 범위 또는 권한을 부여합니다. 해당 요청과 함께 Authorization 헤더에 이 토큰을 보냅니다. 자세한 내용은 인증참조하세요.

4. curl 요청 만들기

          `curl` 명령을 사용하여 요청을 수행합니다. 자세한 정보는 [cURL 설명서](https://curl.se/docs/manpage.html)를 참조하세요.

해당 요청에 다음 옵션 및 값을 지정합니다.

•         **
          `--request` 또는 `-X`** 는 HTTP 메서드가 값으로 따라옵니다. 자세한 내용은 [HTTP 메서드](#http-method)를 참조하세요.
  

•         **
          `--url`
          ** 뒤에 전체 경로가 값으로 따라옵니다. 전체 경로는 GitHub REST API의 기본 URL(`https://api.github.com` 또는 `https://api.SUBDOMAIN.ghe.com`)과 엔드포인트의 경로를 포함하는 URL입니다. 여기서 어떤 위치에서 액세스하는지에 따라 다릅니다GitHub`https://api.github.com/PATH`. 엔드포인트의 경로로 바꿉다 `PATH` . 자세한 내용은 [경로](#path)를 참조하세요.
  

  쿼리 매개 변수를 사용하려면 경로 끝에 ?를 추가한 다음 쿼리 매개 변수 이름과 값을 parameter_name=value 양식으로 추가합니다. 쿼리 매개 변수가 여러 개이면 &로 구분합니다. 쿼리 문자열에서 배열을 보내려면 배열 항목당 쿼리 매개 변수를 한 번 사용하고 쿼리 매개 변수 이름 뒤에 []을(를) 추가 합니다. 예를 들어 두 리포지토리 ID의 배열을 제공하려면 ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID를 사용합니다. 자세한 내용은 쿼리 매개 변수를 참조하세요. 예제는 쿼리 매개 변수를 사용하는 예제 요청을 참조하세요.

•         **
          `--header` 또는 `-H`:**
  

  * ** Accept:Accept 헤더에 미디어 유형을 전달합니다. Accept 헤더에 여러 미디어 유형을 전달하려면 미디어 유형을 쉼표로 구분합니다. 예를 들면 Accept: application/vnd.github+json,application/vnd.github.diff와(과) 같습니다. 자세한 내용은 Accept 및 미디어 유형을 참조하세요. * ** X-GitHub-Api-Version:X-GitHub-Api-Version 헤더에 API 버전을 전달합니다. 자세한 내용은 X-GitHub-Api-Version 참조하세요. * ** Authorization:**Authorization 헤더에 인증 토큰을 전달합니다. 대부분의 경우 Authorization: Bearer 또는 Authorization: token을 사용하여 토큰을 전달할 수 있습니다. 그러나 JWT(JSON 웹 토큰)를 전달하는 경우 Authorization: Bearer를 사용해야 합니다. 자세한 내용은 인증참조하세요. Authorization 헤더를 사용하는 요청의 예제는 본문 매개 변수를 사용한 예제 요청을 참조하세요.

•         **
          `--data` 또는 `-d`** JSON 개체 내의 모든 본문 매개 변수가 뒤에 옵니다. 요청에 본문 매개 변수를 지정할 필요가 없는 경우 이 옵션을 생략합니다. 자세한 내용은 [본문 매개 변수](#body-parameters)를 참조하세요. 예제는 [본문 매개 변수를 사용하는 예제 요청](#example-request-using-body-parameters-1)을 참조하세요.
  

예제 요청

다음 예제 요청에서는 "Octocat 가져오기" 엔드포인트를 사용하여 Octocat을 ASCII 아트로 반환합니다.

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

쿼리 매개 변수를 사용하는 예제 요청

          ["공개 이벤트 나열" 엔드포인트](/rest/activity/events#list-public-events)는 기본적으로 30개의 문제를 반환합니다. 다음 예제에서는 `per_page` 쿼리 매개 변수를 사용하여 30개가 아닌 2개의 문제를 반환하고 `page` 쿼리 매개 변수를 사용하여 결과의 첫 번째 페이지만 가져옵니다.

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

본문 매개 변수를 사용한 예제 요청

다음 예제에서는 문제 엔드포인트 만들기를 사용하여 지정된 리포지토리에 새 문제를 만듭니다. 이전에 만든 인증 토큰으로 YOUR-TOKEN을(를) 바꾸십시오.

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

상태 코드 및 헤더를 보려면 요청을 보낼 때 --include 또는 --i 옵션을 사용합니다.

예를 들어 이 요청은 지정된 리포지토리의 문제 목록을 가져옵니다.

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

또한 다음과 같은 응답 코드와 헤더를 반환합니다.

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

이 예제에서 응답 코드는 성공적인 요청을 나타내는 200입니다.

예를 들어 >를 사용하여 응답을 파일로 리디렉션할 수 있습니다. 다음 예제에서는 리포지토리를 소유하는 계정의 이름으로 REPO-OWNER을(를) 대체하고, 리포지토리의 이름으로 REPO-NAME을(를) 대체하십시오.

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

그런 다음 jq를 사용하여 각 이슈의 제목 및 작성자 ID를 가져올 수 있습니다.

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

이전 두 명령은 다음과 같이 반환합니다.

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

jq에 대한 자세한 정보는 jq 설명서를 참조하세요.