Human-Oriented Documentation

GitHub API is great in that it provides handy ways to deal with your GitHub resources programmatically. Its documentation is also great, which sets a good example for RESTful API designers. Let's look at one way in which GitHub API excels.

GitHub API is categorized by resources, like repositories, issues and pull requests. For each resource the API is further listed by things to do. For example, for repositories, the API  are listed as "List your repositories," "Create," etc.

Repos API

For every thing to do, it details the method and URL, parameters, input and response example.

How to create an issue

Let's look at Atlassian's Jira API.  The also list them by resources, like issues, filters and projects. Instead of using a title of just "Issue," they use a URL, like:

http://example.com:8080/jira/rest/api/2/issue

to represent issue resource. And for each resource, the API is not listed by things to do, but by available URLs.

Issues API 

Further, each URL is neither explained by what to do with the resource, but by available HTTP methods and what each method does.

POST method for an issue API

The GitHub approach is different from the Jira approach. I call the GitHub way human-oriented. When we read API documentation, we do not have in mind web resources, URL and HTTP methods first.  We solve problems. Web resources, URL and HTTP methods are about how to solve our problem, not the problem itself. GitHub API documentation starts directly from the problem and gives the solution. This is the better way.