github-api🔗 i

1Authentication & Initialization🔗 i

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

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

'password authentication simply uses your GitHub username and password.

'personal-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 usernamepassword-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.

2A Note on Identity Security🔗 i

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

3Example🔗 i

4Working with JSON Data🔗 i

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.

5Gist API🔗 i

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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-type])

→github-response?

api-req:github-api-req/c

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

6Gist Examples🔗 i

(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-reqnew-gist-id

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

(github-star-gist github-reqnew-gist-id)

(github-gist-starred? github-reqnew-gist-id)

(github-unstar-gist github-reqnew-gist-id)

(github-gist-starred? github-reqnew-gist-id)

(github-fork-gist github-reqnew-gist-id)

(github-list-gist-forks github-reqnew-gist-id)

(github-get-user-gists github-requsername)

7Events🔗 i

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

procedure

( github-list-events api-req

repo-owner

repo

[ #:media-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-type])

→github-response?

api-req:github-api-req/c

user:string?

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

8Feeds🔗 i

For more information about feeds, go here

procedure

( github-list-feeds api-req

[ #:media-typemedia-type]) → github-response?

api-req:github-api-req/c

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

procedure

( github-list-notifications api-req

[ #:media-typemedia-type])

→github-response?

api-req:github-api-req/c

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

9Issues🔗 i

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-typemedia-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-typemedia-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-typemedia-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-typemedia-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

[ #:bodybody

#:assigneeassignee

#:milestonemilestone

#:labelslabel

#:media-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

title:string?

body:string? =""

assignee:string? =""

milestone:string? =""

label:(listofstring? )=null

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

procedure

( github-edit-issue api-req

repo-owner

repo-name

[ #:titletitle

#:bodybody

#:assigneeassignee

#:milestonemilestone

#:labelslabel

#:media-typemedia-type]) → github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

title:string? =""

body:string? =""

assignee:string? =""

milestone:string? =""

label:(listofstring? )=null

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

procedure

( github-get-issue api-req

repo-owner

repo-name

issue-number

[ #:media-typemedia-type]) → github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

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

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

procedure

( github-list-issue-comments api-req

repo-owner

repo-name

issue-number

[ #:media-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

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

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

procedure

( github-list-comments api-req

repo-owner

repo-name

[ #:media-typemedia-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-typemedia-type]) → github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

comment-id:(or/cnumber? string? )

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

procedure

( github-create-comment api-req

repo-owner

repo-name

issue-number

comment-body

[ #:media-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

issue-number:(or/cnumber? 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-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

comment-id:(or/cnumber? 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-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

comment-id:(or/cnumber? string? )

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

10Issue Examples🔗 i

(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"))

11Repositories🔗 i

procedure

( github-list-assignees api-req

repo-owner

repo-name

[ #:media-typemedia-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-typemedia-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"

12Git Data🔗 i

Click here for more information on the Git Data API.

procedure

( github-get-blob api-req

repo-owner

repo-name

sha

[ #:media-typemedia-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-typemedia-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-typemedia-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-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo-name:string?

message:string?

tree:string?

parents:(listofstring? )

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

13Organizations🔗 i

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

procedure

( github-list-orgs api-req

[ #:media-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-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-typemedia-type])

→github-response?

api-req:github-api-req/c

repo-owner:string?

repo:string?

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

14Users🔗 i

procedure

( github-get-user api-req

user

[ #:media-typemedia-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-typemedia-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-typemedia-type])

→github-response?

api-req:github-api-req/c

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

15Webhooks & Service Hooks🔗 i

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-typecontent-type

#:secretsecret

#:insecure-sslinsecure-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-typemedia-type]) → github-response?

api-req:github-api-req/c

repo-owner:string?

repo:string?

hook-id:(or/cstring? 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/cstring? 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/cstring? 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/cstring? number? )

16Webhooks Example🔗 i

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

#:insecure-ssl"0"

#:content-type"json"))

(define hook(github-hook-repo github-requsernamemy-repo"web"config))

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

(define del-hook(thunk(github-delete-hook github-requsernamemy-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"))