Getting started

To start using the API, one needs to initialize the main API entrypoint, namely the GitHub class. One does not necessarily have to authenticate for this, but it is better to authenticate as it allows one to perform 5000 requests per hour instead of just 60 for unauthenticated users. However, if all you want is to give the bindings a quick try this can be a good option.

Authenticating can be done using either your username and password, or an access token.

An access token can be retrieved using the OAuth2 protocol, using Zinc. To do this, you might want to take a look at the documentation of Zinc SSO.

The access token can also be made manually (called a Personal access token), via the following link (you need to be logged in for this link to work): Personal access tokens. This is the easiest and quickest way to get started with the API. Note that you should treat this token as a password.

1.1. Initializing the main API entry point

The class GitHub functions as the main entry point for the API. From there, one can query either the logged in user (i.e. you) or a user by specifying the name, by sending the messages GitHub>>user and GitHub>>user: respectively. These messages will return an instance of GHUser. The following script shows how to initialize the API and request for a user: 

| github user |

" Initialize using an access token... "
github := GitHub initializeWithAccessToken: 'f1ct10n4l4cc3sst0k3n'.

" ... or using a username and password combination. "
github := GitHub initializeWithUsername: 'JohnDoe' password: '123password'.

" ... or without authenticating yourself.
  Note that this limits the amount of requests and resources you can access. "
github := GitHub initializeAnonymously.

" Get the currently logged in user, which returns an instance of GHUser.
  This fails signalling a GHBadCredentialsError if you did not authenticate. "
user := github user.

" Get a user by their username. "
user := github user: 'MaryJane'.

1.2. Error handling

Errors can be handled with the regular Smalltalk syntax: 

[ github user ]
   on: GHBadCredentialsError
   do: [ UIManager default inform: 'Incorrect username or password!' ]

The GitHub package contains several Error classes by default, containing a class comment explaining the conditions under which they are thrown.

Furthermore, other packages might contain Error classes as well, such as GitHub-Pull-Requests for merge failures. View the 4 documentation of that package and the class comments for more detail.

1.3. Updating objects

Send GHObject>>update to update a domain object, and send GHObject>>isOutdated to test if it is outdated. The #update method uses #isOutdated internally.

1.4. Next steps

The next step is to request a user's repository. One can do this by sending repository: with a repository's name as argument, or sending repositories to get all of the repositories of the user. These methods return instances of GHRepository (or an Array of them), and can be asked several questions such as defaultBranch.

For more operations, such as committing, on repositories, see the following API documentation:

Furthermore, there is documentation explaining the internals of the bindings: 5 Internals.