GitHub has become extremely popular as the social collaborative coding platform for building code as well as contributing to other repositories. It is used by developers to create, build, and deploy software, with usage varying from individual projects to various enterprises using it as part of their processes. GitHub has extensive API documentation for its services at https://developer.github.com/v3/.
The following section covers in detail how GitHub handles all the different patterns we covered in earlier chapters.
The following commands show how to use unauthenticated cURL commands to get data for a user, to get details for the repositories, and so on.
The following command gets details for the javaee-samples user:
curl https://api.github.com/users/javaee-samples { "login": "javaee-samples", "id": 6052086, "avatar_url": "https://avatars.githubusercontent.com/u/6052086?", "gravatar_id": null, "url": "https://api.github.com/users/javaee-samples", "html_url": "https://github.com/javaee-samples", "followers_url": "https://api.github.com/users/javaee-samples/followers", "following_url": "https://api.github.com/users/javaee-samples/following{/other_user}", "gists_url": "https://api.github.com/users/javaee-samples/gists{/gist_id}", "starred_url": "https://api.github.com/users/javaee-samples/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/javaee-samples/subscriptions", "organizations_url": "https://api.github.com/users/javaee-samples/orgs", "repos_url": "https://api.github.com/users/javaee-samples/repos", "events_url": "https://api.github.com/users/javaee-samples/events{/privacy}", "received_events_url": "https://api.github.com/users/javaee-samples/received_events", "type": "Organization", "site_admin": false, "name": "JavaEE Samples", "company": null, "blog": "https://arungupta.ci.cloudbees.com/", "location": null, "email": null, "hireable": false, "bio": null, "public_repos": 11, "public_gists": 0, "followers": 0, "following": 0, "created_at": "2013-11-27T17:17:00Z", "updated_at": "2014-07-03T16:17:51Z"
Note
As shown in the preceding commands, there are different URLs in the preceding response, which can be used to get details such as followers, commits, and so on. This style of presenting the URLs is different from the HATEOAS samples we covered earlier in the book using links, href, rel, and so on. This shows how different platforms choose various ways to provide a connected service, which is self-explanatory.
To get repos for a user with pagination, we can use the query as shown:
curl https://api.github.com/users/javaee-samples/repos?page=1&per_page=10 …..
GitHub API uses OAuth2 for authenticating users for the requests. All developers working with GitHub API need to register their application. A registered application is assigned a unique client ID and client secret.
For more details on getting authenticated requests for a user, check https://developer.github.com/v3/oauth/.
The following table covers how GitHub API uses verbs for a specific action to a resource:
|
Verb |
Description |
|---|---|
|
|
This is used to get the HTTP header info |
|
|
This is used to retrieve resources such as user details |
|
|
This is used for creating resources such as merging pull requests |
|
|
This is used for partial updates to resources |
|
|
This is used for replacing resources such as updating users |
|
|
This is used for deleting resources such as removing a user as a collaborator |
GitHub API uses version v3 in its URI. The default version of the API may change in the future. In case the client is depending on a particular version, they recommend sending an Accept header explicitly, as shown:
Accept: application/vnd.github.v3+json
As covered in Chapter 2, Resource Design, client-side errors are indicated by 400 error codes. GitHub uses a similar convention for denoting errors.
If a client using the API sends an invalid JSON, a 400 Bad Request response is returned back to the client. If a client using the API misses to send a field as part of the request body, a 422 Unprocessable Entity response is returned to the client.
The GitHub API also supports rate limiting so that the server is not overburdened with too many requests from some rogue client causing it to fail. In case of requests using Basic authentication or OAuth, the client is allowed to make up to 5,000 requests per hour. In case of unauthenticated requests, the rate limit is up to 60 requests per hour for a client. GitHub uses the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to tell the status of the rate limits.
Thus, we have covered details on the GitHub API on how they choose to implement some of the REST principles we have covered so far in this book. The next section covers the Facebook Open Graph REST API for topics such as versioning, error handling, rate limiting, and so on.