Improved REST API documentation

We’re excited to announce some big improvements to our REST API documentation. We know developers rely on this documentation to integrate with GitHub, and we are committed to making it trustworthy, easy to find, and easy to use.

Prior to generating our REST API documentation directly from our OpenAPI schema, our Docs Team painstakingly generated the documentation manually, using a framework that was fragile and couldn’t scale with our REST API. Since the switch to using OpenAPI, we’ve improved our ability to generate accurate, detailed documentation automatically, and we’ve made these pages easier to navigate and read. We still have work to do, but we’re excited to share some of the recent changes to the REST API documentation.

Three-column layout

Previously, documentation for operations with large request bodies or responses required a significant amount of scrolling to view all of the operation’s documentation. We’ve moved to a three-column layout to improve the readability of our docs and make it easier to see parameters with example requests and responses grouped together. Small screens will still display a two-column layout.

In the new layout, we locate all of the example request and response content in the right column, and allow you to select the example and language using dropdown and sub-navigation components. The language you select will be the default language used on future visits to the REST API documentation.

The example column on the right in the three-column layout is sticky to allow you to cross-reference the example values to the request body parameters without excessive scrolling.

Improved examples

The GitHub Docs Team strives to provide meaningful examples in our REST API documentation that match between request body and response. Before the recent changes, the example values for request body parameters were either a generic placeholder value or used the name of the parameter as the value. This was a confusing experience.

Examples are now driven entirely from our OpenAPI schema—where we have made the existing data more meaningful and created a consistent model for writing examples going forward.

We also want to ensure folks know about our wonderful GitHub CLI, which allows you to easily interact with GitHub and GitHub’s REST API directly from the command line. So, we’ve included GitHub CLI examples directly in our REST API documentation.

Improved parameter table information

Moving to a three-column layout meant we had to redesign our parameter table to fit into a smaller space while making them easy to scan and read. We now generate more of the parameter table information from the OpenAPI (e.g., enumerated values), and we made general design and organizational improvements. Enumerated values are preceded by the text, “Can be one of” and are listed below default values.

Response schemas

One of the most common requests that we received was to include the response schema directly in the API documentation, and we listened! The response schema gives you a more complete picture of the possible response values because it includes information about required properties, nullable properties, enumerated values, and much more.

Now, you can toggle between an example response and response schema for each operation in the REST API documentation.

Status codes

Previously, the only way to determine the possible status codes in an operation was to check the codes embedded in the examples. Now, the status code information is presented in an easy-to-scan table for every operation.

Improve information architecture

When we migrated developer content to docs.github.com several years ago, the site’s information architecture at the time was not set up for API documentation, so we combined operations into very long pages to make it work. These long pages didn’t perform or scale well. Now, we’ve broken up the REST API into categories and subcategories to improve the readability and performance of these pages, so you can find the documentation you need efficiently.

Navigation

With the move to a three-column layout, we needed to remove the table of contents that listed the operations on each page. Now, all of the pages and operations in the REST API are located directly in the sidebar navigation. You can still link to any operation on a page, and the sidebar will highlight the active operation’s anchor link as you scroll.

We’d love to hear from you!

We have more updates in the future, but we’d love to hear your feedback! Please feel free to drop a comment in this discussion.

We want our OpenAPI schema to be as complete and accurate as possible. If you see something that’s wrong or unclear in our REST API documentation, please open an issue in our public OpenAPI description repository.

This was a cross-team collaboration, but I’d like to give a special thanks to @gracepark and @rsese from GitHub Docs engineering and @skedwards88 from GitHub Docs who helped me get these updates out there to you!

Written by

Rachael Sewell

@rachmari