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.
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:
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.
http://example.com:8080/jira/rest/api/2/issueto represent issue resource. And for each resource, the API is not listed by things to do, but by available URLs.
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|