이 버전의 GitHub Enterprise Server는 다음 날짜에 중단됩니다. 2023-12-20. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

REST API의 리소스

이 문서의 내용

GitHub Enterprise Server API에서 제공하는 리소스를 탐색하는 방법을 알아봅니다.

스키마

API는 http(s)://HOSTNAME/api/v3에서 액세스됩니다. 모든 데이터가 JSON으로 전송되고 수신됩니다.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/users/octocat/orgs

> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> X-GitHub-Enterprise-Version: 3.7.0
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

빈 필드는 생략되는 대신 null로 포함됩니다.

모든 타임스탬프는 UTC 시간, ISO 8601 형식으로 반환됩니다.

YYYY-MM-DDTHH:MM:SSZ

타임스탬프의 표준 시간대에 대한 자세한 내용은 이 섹션을 참조하세요.

요약 표현

리소스 목록을 가져올 때 응답에는 해당 리소스에 대한 특성의 _하위 집합_이 포함됩니다. 리소스의 "요약" 표현입니다. (일부 특성은 컴퓨팅 비용이 많이 들어 API가 제공하기 어렵습니다. 성능상의 이유로 요약 표현은 해당 특성을 제외합니다. 이러한 특성을 가져오려면 "자세한" 표현을 가져옵니다.)

예: 리포지토리 목록을 가져오는 경우 각 리포지토리의 요약 표현을 가져옵니다. 여기서는 octokit 조직이 소유한 리포지토리 목록을 가져옵니다.

GET /orgs/octokit/repos

자세한 표현

개별 리소스를 가져올 때 응답에는 일반적으로 해당 리소스에 대한 모든 특성이 포함됩니다. 리소스의 "자세한" 표현입니다. (경우에 따라 권한 부여는 표현에 포함된 자세한 정도에 영향을 줍니다.)

예: 개별 리포지토리를 가져올 때 리포지토리의 자세한 표현을 가져옵니다. 여기서는 octokit/octokit.rb 리포지토리를 가져옵니다.

GET /repos/octokit/octokit.rb

설명서는 각 API 메서드에 대한 예제 응답을 제공합니다. 예제 응답은 해당 메서드에서 반환되는 모든 특성을 보여 줍니다.

인증

GitHub에서는 토큰을 만들어 REST API에 인증하는 것이 좋습니다. 만들 토큰 유형에 대한 자세한 내용은 "REST API에 인증"을 참조하세요.

요청의 Authorization 헤더에 토큰을 전송하여 요청을 인증할 수 있습니다.

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

참고: 대부분의 경우 Authorization: Bearer 또는 Authorization: token을 사용하여 전달할 수 있습니다. 그러나 JWT(JSON 웹 토큰)를 전달하는 경우 Authorization: Bearer를 사용해야 합니다.

토큰 없이 또는 권한이 부족한 토큰으로 REST API 엔드포인트를 사용하려고 하면 404 Not Found 또는 403 Forbidden 응답을 받게 됩니다.

OAuth2 키/비밀

사용 중단 알림: GitHub는 쿼리 매개 변수를 사용한 API에 대한 인증을 중단합니다. API에 대한 인증은 HTTP 기본 인증을 사용하여 수행해야 합니다. 예정된 브라운아웃을 포함한 자세한 내용은 블로그 게시물을 참조하세요.

쿼리 매개 변수를 사용한 API에 대한 인증은 사용 가능한 동안에도 보안 문제로 인해 더 이상 지원되지 않습니다. 대신 통합자가 헤더에서 액세스 토큰, client_id 또는 client_secret을 이동할 것을 권장합니다. GitHub는 고급 알림이 포함된 쿼리 매개 변수에 의한 인증을 제거한다고 발표할 것입니다.

curl -u my_client_id:my_client_secret 'http(s)://<em>HOSTNAME</em>/api/v3/user/repos'

client_id 및 client_secret을 사용해도 사용자로 인증하지 않으며, 속도 제한을 늘리려는 경우에만 OAuth OAuth app을(를) 식별합니다. 권한은 애플리케이션이 아닌 사용자에게만 부여되며 인증되지 않은 사용자에게 표시되는 데이터만 다시 가져옵니다. OAuth app의 클라이언트 비밀을 사용자에게 유출하지 마세요.

프라이빗 모드에서 OAuth2 키와 비밀을 사용하여 인증할 수 없으며 인증을 시도하면 401 Unauthorized가 반환됩니다. 자세한 내용은 “프라이빗 모드 사용 설정”을 참조하세요.

실패한 로그인 제한

잘못된 자격 증명으로 인증하면 401 Unauthorized가 반환됩니다.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/enterprise/3.7/rest"
> }

짧은 기간 내에 잘못된 자격 증명을 사용한 여러 요청을 검색하면 API는 403 Forbidden을 나타내며 해당 사용자에 대한 모든 인증 시도(유효한 자격 증명을 사용한 시도 포함)를 일시적으로 거부합니다.

> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.7/rest"
> }

매개 변수

많은 API 메서드는 선택적 매개 변수를 사용합니다. GET 요청의 경우 경로에 세그먼트로 지정되지 않은 매개 변수를 HTTP 쿼리 문자열 매개 변수로 전달할 수 있습니다.

curl -i "http(s)://<em>HOSTNAME</em>/api/v3/repos/vmg/redcarpet/issues?state=closed"

이 예제에서는 쿼리 문자열에 :state가 전달되는 동안 경로의 :owner 및 :repo 매개 변수에 대해 'vmg' 및 'redcarpet' 값이 제공됩니다.

POST, PATCH, PUT 및 DELETE 요청의 경우 URL에 포함되지 않은 매개 변수는 Content-Type이 'application/json'인 JSON으로 인코딩되어야 합니다.

curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' http(s)://<em>HOSTNAME</em>/api/v3/authorizations

루트 엔드포인트

루트 엔드포인트에 대해 GET 요청을 실행하여 REST API에서 지원하는 모든 엔드포인트 범주를 가져올 수 있습니다.

$ curl -u USERNAME:PASSWORD http(s)://<em>HOSTNAME</em>/api/v3

GraphQL 전역 노드 ID

REST API를 통해 node_id를 찾은 후 GraphQL 작업에서 사용하는 방법에 대한 자세한 내용은 "전역 노드 ID 사용"에 대한 가이드를 참조하세요.

HTTP 동사

가능한 경우 GitHub Enterprise Server REST API는 각 작업에 적절한 HTTP 동사를 사용하려고 합니다. HTTP 동사는 대/소문자를 구분합니다.

동사설명
HEADHTTP 헤더 정보만 가져오기 위해 어떤 리소스에 대해서도 실행할 수 있습니다.
GET리소스를 검색하는 데 사용됩니다.
POST리소스를 만드는 데 사용됩니다.
PATCH부분 JSON 데이터로 리소스를 업데이트하는 데 사용됩니다. 예를 들어, 이슈 리소스에는 title 및 body 특성이 있습니다. PATCH 요청은 하나 이상의 특성을 수락하여 리소스를 업데이트할 수 있습니다.
PUT리소스 또는 컬렉션을 바꾸는 데 사용됩니다. body 특성이 없는 PUT 요청의 경우 Content-Length 헤더를 0으로 설정해야 합니다.
DELETE리소스를 삭제하는 데 사용됩니다.

하이퍼미디어

모든 리소스에는 다른 리소스에 연결된 하나 이상의 *_url 속성이 있을 수 있습니다. 이는 적절한 API 클라이언트가 자체 URL을 생성할 필요가 없도록 명시적 URL을 제공하기 위한 것입니다. API 클라이언트는 이를 사용하는 것이 좋습니다. 이렇게 하면 개발자가 API를 더 쉽게 업그레이드할 수 있습니다. 모든 URL은 적절한 RFC 6570 URI 템플릿이어야 합니다.

그러면 uri_template gem과 같은 항목을 사용하여 이러한 템플릿을 확장할 수 있습니다.

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

크로스-원본 자원 공유

API는 모든 원본의 AJAX 요청에 대해 CORS(원본 간 리소스 공유)를 지원합니다. CORS W3C 권장 사항 또는 HTML 5 보안 가이드의 이 소개를 읽을 수 있습니다.

http://example.com에 도달한 브라우저에서 보낸 샘플 요청은 다음과 같습니다.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

CORS 사전 실행 요청은 다음과 같습니다.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

JSON-P 콜백

GET 호출에 ?callback 매개 변수를 전송하여 결과를 JSON 함수로 래핑할 수 있습니다. 일반적으로 브라우저가 도메인 간 이슈를 해결하여 웹 페이지에 GitHub Enterprise Server 콘텐츠를 포함하려는 경우에 사용됩니다. 응답에는 일반 API와 동일한 데이터 출력 및 관련 HTTP 헤더 정보가 포함됩니다.

$ curl http(s)://<em>HOSTNAME</em>/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["http(s)://<em>HOSTNAME</em>/api/v3?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

JavaScript 처리기를 작성하여 콜백을 처리할 수 있습니다. 다음은 사용해 볼 수 있는 최소한의 예제입니다.

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'http(s)://HOSTNAME/api/v3?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

모든 헤더는 HTTP 헤더와 동일한 문자열 값이며 유의해야 할 한 가지 예외는 Link입니다. Link 헤더는 미리 구문 분석되며 [url, options] 튜플 배열로 제공됩니다.

링크

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

...콜백 출력에 표시되는 내용:

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

시간대

새 커밋 만들기와 같이 새 데이터를 만드는 일부 요청에서는 타임스탬프를 지정하거나 생성할 때 표준 시간대 정보를 제공할 수 있습니다. 우선 순위에 따라 다음 규칙을 적용하여 이러한 API 호출에 대한 표준 시간대 정보를 결정합니다.

이러한 규칙은 API에서 반환된 데이터가 아니라 API에 전달된 데이터에만 적용됩니다. "스키마"에서 설명한 대로 API에서 반환된 타임스탬프는 UTC 시간 ISO 8601 형식입니다.

ISO 8601 타임스탬프에 표준 시간대 정보를 명시적으로 제공

타임스탬프를 지정할 수 있는 API 호출의 경우 정확한 타임스탬프를 사용합니다. 이에 대한 예제는 메모를 관리하는 API입니다. 자세한 내용은 "Git 데이터베이스"을(를) 참조하세요.

이러한 타임스탬프는 2014-02-27T15:05:06+01:00과 같습니다. 또한 이러한 타임스탬프를 지정하는 방법은 이 예제를 참조하세요.

Time-Zone 헤더 사용

Olson 데이터베이스의 이름 목록에 따라 표준 시간대를 정의하는 Time-Zone 헤더를 제공할 수 있습니다.

curl -H "Time-Zone: Europe/Amsterdam" -X POST http(s)://<em>HOSTNAME</em>/api/v3/repos/github-linguist/linguist/contents/new_file.md

즉, 이 헤더가 정의하는 표준 시간대에서 API 호출이 수행되는 순간의 타임스탬프를 생성합니다. 예를 들어 콘텐츠를 관리하는 API는 추가 또는 변경마다 git 메모를 생성하고 현재 시간을 타임스탬프로 사용합니다. 자세한 내용은 "리포지토리"을(를) 참조하세요. 이 헤더는 현재 타임스탬프를 생성하는 데 사용되는 표준 시간대를 결정합니다.

사용자에 대해 마지막으로 알려진 표준 시간대 사용

Time-Zone 헤더가 지정되지 않고 API에 대해 인증된 호출을 수행하는 경우 인증된 사용자에 대해 마지막으로 알려진 표준 시간대를 사용합니다. 마지막으로 알려진 표준 시간대는 GitHub Enterprise Server 웹 사이트로 이동할 때마다 업데이트됩니다.

다른 표준 시간대 정보 없이 UTC로 기본 설정

위의 단계를 수행해도 정보가 생성되지 않으면 UTC를 표준 시간대로 사용하여 git 커밋을 만듭니다.