@gr2m/octokit-rest-routes

octokit-rest-routes

machine-readable, always up-to-date GitHub REST API route specifications

⚠️ This module is work in progress. It does not follow semantic versioning yet. Feedback welcome :)

Usage

const ROUTES = require('@gr2m/octokit-rest-routes')

returns an object with keys being the route scopes such as activity, issues, repositories, etc (one for navigation header in the sidebar at https://developer.github.com/v3/).

The value for each scope is an array of REST API endpoint specification.

Example

Here is an excerpt for reference

{
  ...
  "repositories": [
    {
      "name": "List your repositories",
      "enabledForApps": false,
      "method": "GET",
      "path": "/user/repos",
      "description": "List repositories that are accessible to ...",
      "params": [
        {
          "name": "visibility",
          "type": "enum",
          "options": [
            "all",
            "public",
            "private"
          ],
          "description": "Can be one of `all`, `public`, or `private`.",
          "default": "all",
          "required": false
        },
        ...
      ],
      "documentationUrl": "https://developer.github.com/v3/repos/#list-your-repositories"
    },
    ...
  ],
  ...
}

How it works

This package updates itself using a daily cronjob running on Travis. All routes/*.json files as well as index.js is generated by bin/octokit-rest-routes.js. Run node bin/octokit-rest-routes.js --usage for instructions.

The update script is scraping GitHub’s REST API documentation pages and extracts the meta information using cheerio and a ton of regular expressions :)

For simpler local testing and tracking of changes all loaded pages are cached in the cache/ folder.

⚠️ TBD: cron job to send pull request on changes (#12)

1. Find documentation pages

• Index page cached in cache/v3/index.html
• Result cached in cache/pages.json

Opens https://developer.github.com/v3/, find all documentation page URLs in the side bar navigation.

2. On each documentation page, finds sections

• Documentation pages cached in cache/v3/*/index.html, e.g. cache/v3/repos/index.html
• Documentation sub pages cached in cache/v3/*/*/index.html, e.g. cache/v3/repos/branches/index.html
• All sections found on pages are cached next to the index.html files, e.g. cache/v3/repos/sections.json
• HTML of sections are stored next to the index.html files, e.g. cache/v3/repos/create.html

Loads HTML of each documentation page, finds sections in page.

3. In each section, finds endpoints

• Some sections don’t have endpoints, such as Notifications Reasons
• Some sections have multiple endpoints, see #3

Loads HTML of documentation page section. Turns it into routes/*.json file. In some cases the HTML cannot be turned into an endpoint using the implemented patterns. For these cases custom overrides are defined.

LICENSE

MIT