About the Learning Lab API

Overview

This describes the resources that make up the official GitHub Learning Lab REST API.

When possible, the Learning Lab API tries to maintain usage parity with the GitHub API but they are separate and different! Although they generally follow the same API conventions, there may be subtle differences.

1. Current Version
2. Schema
3. Authentication
4. Parameters
5. Root Endpoint
6. Client Errors
7. HTTP Redirects
8. HTTP Verbs
9. Pagination

Current Version

By default, all requests to https://lab.github.com/api receive the v0 version of the REST API.

This API is still in an early stage of development, so most aspects are still subject to change.

Schema

All API access is over HTTPS and accessed from https://lab.github.com/api/v0. All data is sent and received as JSON.

$ curl -i https://lab.github.com/api/v0
    HTTP/1.1 200 OK
    Server: Cowboy
    Date: Mon, 05 Aug 2019 18:55:49 GMT
    Content-Type: application/json; charset=utf-8
    Connection: Keep-alive
    Etag: W/"2-vyGp6PvFo4RvsFtPoIWeCReyIC8"

Blank fields are included as null instead of being omitted.

All timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

For more information about timezones in timestamps, see this section.

Authentication

Authenticating through the Learning Lab API requires having a Learning Lab personal access token. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden in some places. This is to prevent the accidental leakage of private data to unauthorized users.

curl -H "Authorization: token YOUR-TOKEN" https://lab.github.com/api/v0

Learning Lab only accepts sending tokens in request headers.

Failed Login

Authenticating with invalid credentials will return 401 Unauthorized:

$ curl -H "Authorization: token YOUR-TOKEN" https://lab.github.com/api/v0
    HTTP/1.1 401 Unauthorized
    {
      "message": "Bad credentials",
      "documentation_url": "https://developer.github.com/v3"
    }

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

curl -i "https://lab.github.com/api/v0/courses/githubtraining?limit=50"

In this example, the githubtraining value is provided in the path, while limit is passed in the query string.

Root endpoint

You can issue a GET request to the root endpoint to get more information about what the REST API v0 supports:

curl https://lab.github.com/api/v0

Client Errors

Error Code	Description
400	The querystring contained invalid parameters. For example, if you passed a 'limit' parameter a string instead of a number.
401	When the requester has not authenticated with the API
403	When the course data is public, but it's not yours. If you tried to update someone else's progress in a course they're taking.
404	Page not found. We may send this instead of a 400 or 403 even if what you're requesting is valid but you need credentials to access it.
405	You're accessing a valid route, but the HTTP verb isn't supported. For example if you tried POST /courses
408	The request timed out. This often happens simply due to a slow network connection.
422	Unprocessable Entity. You may have sent a string or object that could not be parsed or read.
429	API rate limit exceeded. The default rate limit is 60 requests per hour. Authenticated requests get 5000 per hour.

HTTP redirects

API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status Code	Description
301	Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.
302, 307	Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources.
POST	Used for creating resources.
PATCH	Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PUT	Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE	Used for deleting resources.

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the ?offset parameter. For some resources, you can also set a custom page size up to 100 with the ?limit parameter. Note that for technical reasons some endpoints may not respect the ?limit parameter.

curl 'https://lab.github.com/api/v0/courses?offset=2&limit=100'

Note that page numbering is 1-based and that omitting the ?limit parameter will return the first page.

For more information on pagination, check out the GitHub API's guide on Traversing with Pagination.