[Github] Getting started with the REST API

Link 요약 정리

Overview

curl https://api.github.com/zen

• Random 문자열

curl https://api.github.com/users/defunkt

• defunkt 유저의 공개된 프로필

curl https://api.github.com/users/defunkt -i

• -i JSON으로 변환

Authentication

• Unauthenticated clients: 한 시간에 60개의 요청 가능
• Authenticated clients: 한 시간에 5000개의 요청 가능

Using personal access tokens

curl -i -u your_username https://api.github.com/users/octocat

> Enter host password for user 'your_username': 

• 이 방법보다는 token을 명령어 자체에 설정하는 방법(아래)을 추천

curl -i -u username:$token https://api.github.com/users/octocat

• 토큰이 shell history에 남는 것을 방지
• 헤더의 x-ratelimit-limit가 5000으로 변경된 것을 확인 가능
• 응답 본문에 plan과 같은 non-public한 정보가 포함됨

토큰 발급 방법: Link

curl -i -u your_username:your_token https://api.github.com/user

• 응답 본문에 plan과 같은 non-public한 정보가 포함됨

Using OAuth tokens for apps

다른 사용자를 대신하여 API를 사용해 개인 정보를 읽거나 써야하는 경우에 사용한다.
OAuth도 token을 사용하는데, 두 가지 큰 기능을 제공한다.

• Revokable access: 사용자는 언제든지 third-party app에 대한 권한을 취소할 수 있다.
• Limited access: 사용자는 third-party app에 대한 권한을 승인하기 전에 토큰이 제공하는 특정 액세스 권한을 검토할 수 있다.

토큰은 web flow를 통해 만들어져야 한다.

• web flow 요약
  1. App은 사용자를 Github로 전송하여 로그인한다.
  2. Github는 앱의 이름을 나타내는 대화상자와 앱이 가진 액세스 수준을 제시한다.
  3. 사용자가 액세스를 승인하면 Github는 사용자를 다시 redirection 시킨다.

Repositories

curl -i https://api.github.com/repos/twbs/bootstrap

• Repo(twbs/bootstrap)의 세부 정보

curl -i -H "Authorization: token $token" \
    https://api.github.com/user/repos

• 인증된 유저(토큰 주인)의 Repo 리스트

curl -i https://api.github.com/users/octocat/repos

• 유저(octocat)의 Repo 리스트

curl -i https://api.github.com/orgs/octo-org/repos

• Organization(octo-org)의 Repo 리스트

응답 정보는 토큰의 권한 범위에 따라 달라진다.

• public_repo scope가 포함된 토큰은 github.com 에서 볼 수 있는 모든 공개 Repo를 포함한 응답을 반환
• repo scope가 포함된 토큰은 github.com 에서 볼 수 있는 모든 공개 및 개인 Repo를 포함한 응답을 반환

curl -i "https://api.github.com/users/octocat/repos?type=owner"

• 유저 octocat이 owner 인 Repo만 반환. (collaborate한 repo는 제외)

Create a repository

Repository를 생성하기 위해선 세부 정보와 구성 정보가 담긴 JSON을 포함한 POST 요청을 작성해야 합니다.

curl -i -H "Authorization: token $token" \
    -d '{ \
        "name": "blog", \
        "auto_init": true, \
        "private": true, \
        "gitignore_template": "nanoc" \
      }' \
    https://api.github.com/user/repos

• nanoc 템플릿으로 gitignore 초기화

curl -i https://api.github.com/repos/pengwynn/blog

> HTTP/1.1 404 Not Found

> {
>    "message": "Not Found"
> }

• 앞서 repo를 private로 만들었기 때문에, 권한없는 요청에 403 또는 404 응답을 준다. (Repo의 존재여부에 상관없이, 개인 repo의 정보 유출을 막기 위해)

Issues

curl -i -H "Authorization: token $token" \
    https://api.github.com/issues

• 유저의 모든 이슈

curl -i -H "Authorization: token $token" \
    https://api.github.com/orgs/rails/issues

• 한 Organization(rails)에 포함되는 이슈 리스트

curl -i https://api.github.com/repos/rails/rails/issues

• 한 Repo(rails/rails)에 포함되는 이슈 리스트

Pagination

curl -i https://api.github.com/repos/rails/rails/issues

> HTTP/1.1 200 OK

> ...
> Link: <https://api.github.com/repositories/8514/issues?page=2>; rel="next", <https://api.github.com/repositories/8514/issues?page=30>; rel="last"
> ...

• Link header: 외부 리소스에 대한 링크 응답을 제공. 이 경우 추가 데이터 페이지를 제공

Creating an issue

curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
   -d '{ \
        "title": "New logo", \
        "body": "We should have one", \
        "labels": ["design"] \
      }' \
   https://api.github.com/repos/pengwynn/api-sandbox/issues

• 생성 정보와 함께 요청
• Location header 와 url 필드를 가진 JSON 응답

Conditional requests

curl -i https://api.github.com/users/defunkt

> HTTP/1.1 200 OK
> ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"

• Etag는 응답의 지문. 이후 요청에서 리소스가 변경되었을 때만 다시 제공하라고 할 수 있음.

curl -i -H 'If-None-Match: "bfd85cbf23ac0b0c8a29bee02e7117c6"' \
   https://api.github.com/users/defunkt

> HTTP/1.1 304 Not Modified

• 304는 리소스가 마지막으로 요청한 이후 변경되지 않았으며 응답에 아무것도 포함되지 않음을 나타낸다.