github-api

While this document contains usage examples, the functional tests found in the functional_tests directory of the github repository provide a good source of usage examples and patterns.

1 Authentication & Initialization

Before you begin making requests to the GitHub api, you must create an identity.

type must be one of the following symbols: 'password 'personal-access-token 'oauth

'password authentication simply uses your GitHub username and password.

'personal-access-token authentication allows you to send your GitHub username and a personal access token (created on your GitHub settings page.)

'oauth uses an OAuth token for authorization.

For more information, see the github api documentation

The data field is a list whose contents are determined by user authentication method.

For 'password or 'personal-token types, your data will be of the form (list username password-or-token), where both username & password-or-token are strings.

The optional #:endpoint keyword sets the root endpoint for making api requests. If you have a GitHub enterprise account, you may wish to change the endpoint. See this for more information on root-endpoints.

If you change the user-agent string, be aware that GitHub has certain rules explicated here

Typically, one would not use this procedure directly but rather pass it along to another function.

The #:method keyword specifies what HTTP verb to use (I.e. "GET", "POST", "PATCH", etc.)

The #:data keyword specifies any information to send along with the request. This is almost always a JSON string.

Finally, #:media-type specifies the format in which you wish to receive data. Practically every github-* procedure has an optional keyword #:media-type that allows you to specify a media-type for a request.

For more information on media types see the GitHub api documentation.

2 A Note on Identity Security

According to the GitHub documentation, personal access tokens are equivalent to your password. Never give it out (and don’t accidently commit your identity!)

Read more about your options for authentication here

3 Example

4 Working with JSON Data

When making requests to the GitHub API, it is common to receive data encoded in the JSON format. This quick section introduces Racket’s JSON handling facilities.

Racket provides a library for working with JSON data, aptly called json.

This is used by the Racket github-api library to encode data before returning it.

To learn more about working with hashes see the Racket guide and the Racket reference on hash-tables.

5 Gist API

The Gist API will return up to 1 megabyte of content from a requested gist.

To see if a file was truncated, check whether or not the key truncated is "true".

To get the full contents of the file, make a request to the url referenced by the key raw_url.

For more information on truncation see the GitHub documentation

The optional keyword description provides a description of the gist. By default it is empty.

procedure (github-list-gist-commits   api-req       gist-id      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-star-gist   api-req             gist-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-unstar-gist   api-req             gist-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-gist-starred?   api-req             gist-id            [ #:media-type media-type])   →   boolean?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-fork-gist   api-req             gist-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-gist-forks   api-req       gist-id      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-delete-gist   api-req             gist-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

gist-id : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-gist-revision   api-req       gist-id       sha      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

gist-id : string?

sha : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-user-gists   api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-my-gists   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-my-starred-gists   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-all-public-gists   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

6 Gist Examples

(define new-gist-id

(let ([response (github-create-gist github-req

(list (cons "file1.txt" "blah blah blah")

(cons "file2.txt" "yadda yadda yadda")))])

(hash-ref (github-response-data response) 'id)))

(github-edit-gist github-req new-gist-id

(list (cons "file2.txt" 'delete)))

(github-star-gist github-req new-gist-id)

(github-gist-starred? github-req new-gist-id)

(github-unstar-gist github-req new-gist-id)

(github-gist-starred? github-req new-gist-id)

(github-fork-gist github-req new-gist-id)

(github-list-gist-forks github-req new-gist-id)

(github-get-user-gists github-req username)

7 Events

For more information on the Events API, see the GitHub documentation

procedure (github-list-events   api-req             repo-owner             repo            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-issue-events   api-req       repo-owner       repo      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-public-org-events   api-req       org      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

org : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-user-received-events   api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-user-received-public-events       api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-user-events   api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-user-public-events   api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

8 Feeds

For more information about feeds, go here

procedure (github-list-feeds   api-req            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-notifications   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

9 Issues

For more information about the Issues API, click here

Furthermore, the Issues API uses custom media types. See this section

procedure (github-list-all-issues   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-my-issues   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-org-issues   api-req       organization      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

organization : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-issues   api-req             repo-owner             repo-name            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-create-issue   api-req       repo-owner       repo-name       title      [ #:body body       #:assignee assignee       #:milestone milestone       #:labels label       #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

title : string?

body : string? = ""

assignee : string? = ""

milestone : string? = ""

label : (listof string?) = null

media-type : string? = "application/vnd.github.v3+json"

procedure (github-edit-issue   api-req             repo-owner             repo-name            [ #:title title             #:body body             #:assignee assignee             #:milestone milestone             #:labels label             #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

title : string? = ""

body : string? = ""

assignee : string? = ""

milestone : string? = ""

label : (listof string?) = null

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-issue   api-req             repo-owner             repo-name             issue-number            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

issue-number : (or/c number? string?)

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-issue-comments   api-req       repo-owner       repo-name       issue-number      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

issue-number : (or/c number? string?)

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-comments   api-req       repo-owner       repo-name      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-comment   api-req             repo-owner             repo-name             comment-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

comment-id : (or/c number? string?)

media-type : string? = "application/vnd.github.v3+json"

procedure (github-create-comment   api-req       repo-owner       repo-name       issue-number       comment-body      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

issue-number : (or/c number? string?)

comment-body : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-edit-comment   api-req       repo-owner       repo-name       comment-id       comment-body      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

comment-id : (or/c number? string?)

comment-body : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-delete-comment   api-req       repo-owner       repo-name       comment-id      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

comment-id : (or/c number? string?)

media-type : string? = "application/vnd.github.v3+json"

10 Issue Examples

(github-create-issue github-req

"eu90h"

"racket-github-api"

"testing-issues-api"

#:body "this is a test of the issues api"

#:assignee "eu90h"

#:labels (list "woo!" "test"))

11 Repositories

procedure (github-list-assignees   api-req       repo-owner       repo-name      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-check-assignee   api-req       repo-owner       repo-name       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

user : string?

media-type : string? = "application/vnd.github.v3+json"

12 Git Data

Click here for more information on the Git Data API.

procedure (github-get-blob   api-req             repo-owner             repo-name             sha            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

sha : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-create-blob   api-req             repo-owner             repo-name             content            [ encoding             #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

content : string?

encoding : string? = "utf-8"

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-commit   api-req             repo-owner             repo-name             sha            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

sha : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-create-commit   api-req       repo-owner       repo-name       message       tree       parents      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo-name : string?

message : string?

tree : string?

parents : (listof string?)

media-type : string? = "application/vnd.github.v3+json"

13 Organizations

For more on Organizations, go "https://developer.github.com/v3/orgs/" "here"

procedure (github-list-orgs   api-req            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-all-orgs   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-user-orgs   api-req       user      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-org   api-req             org            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

org : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-org-members   api-req       org      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

org : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-list-pull-requests   api-req       repo-owner       repo      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

media-type : string? = "application/vnd.github.v3+json"

14 Users

procedure (github-get-user   api-req             user            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

user : string?

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-authenticated-user   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

procedure (github-get-all-users   api-req      [ #:media-type media-type])

→ github-response?

api-req : github-api-req/c

media-type : string? = "application/vnd.github.v3+json"

15 Webhooks & Service Hooks

Webhooks are a sort-of user defined callback in the form of a listening webserver that github sends a message to whenever a certain type of event occurs.

A service hook is a webhook whose type is anything except "web"

To read more, see the GitHub documentation

procedure (github-build-webhook-config   api-req       url      [ #:content-type content-type       #:secret secret       #:insecure-ssl insecure-ssl])

→ github-response?

api-req : github-api-req/c

url : string?

content-type : string? = "form"

secret : string? = ""

insecure-ssl : string? = "0"

Passing any other string results in an error response from the GitHub API.

procedure (github-get-hook   api-req             repo-owner             repo             hook-id            [ #:media-type media-type])   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

hook-id : (or/c string? number?)

media-type : string? = "application/vnd.github.v3+json"

procedure (github-test-push-hook   api-req             repo-owner             repo             hook-id)   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

hook-id : (or/c string? number?)

procedure (github-ping-hook   api-req             repo-owner             repo             hook-id)   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

hook-id : (or/c string? number?)

procedure (github-delete-hook   api-req             repo-owner             repo             hook-id)   →   github-response?

api-req : github-api-req/c

repo-owner : string?

repo : string?

hook-id : (or/c string? number?)

16 Webhooks Example

(define config (github-build-webhook-config "http://example.com"

#:insecure-ssl "0"

#:content-type "json"))

(define hook (github-hook-repo github-req username my-repo "web" config))

(define hook-data (github-response-data hook))

(define del-hook (thunk (github-delete-hook github-req username my-repo (hash-ref hook-data 'id))))

...

(define delete-response (del-hook))

(if (= 204 (github-response-code delete-response))

(displayln "successfully removed webhook")

(displayln "trouble removing webhook"))