# REST

## About this directory

* `lib/rest/index.js` is human-editable.
* `lib/rest/static/*.json` are generated by [scripts](../../script/rest/README.md).

## Editable files

* `lib/rest/index.js` consumes the static decorated schema files and exports `categories`, `operations`, and `operationsEnabledForGitHubApps` used by the REST middleware contextualizer.

## Static files

Generated by `script/rest/update-files.js`:

* `lib/rest/static/dereferenced` - dereferenced OpenAPI schema file for each version of GitHub
* `lib/rest/static/decorated` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML

## Rendering docs

When the server starts, `middleware/contextualizers/rest.js` accesses the data exported from the static decorated JSON files, fetches the data for the current version and requested path, and adds it to the `context` object. The added property is:

* `req.context.currentRestOperations` - all operations with a category matching the current path

Markdown files in `content/rest/reference` use Liquid to loop over these context properties. The Liquid calls HTML files in the `includes` directory to do most of the rendering. Writers can add content to the Markdown files alongside the Liquid.