At Human Made, we often work on WordPress REST API-based projects internally and for clients.
One of the difficulties of any project is having up-to-date documentation available for engineers on the project, especially when onboarding new people. With traditional PHP code, this can be solved by creating inline documentation to document our internal APIs. However, when using the REST API, our API is external, and users may not have access to the codebase. This requires us to document in a completely different way.
Today we’re introducing Restsplain, an automated documentation site for your WordPress REST API. Restsplain is a WordPress plugin you can install on any site and use immediately to browse your API. Customise it to your heart’s content and build native API documentation for your site.
Documentation in the Age of the API
Talk about why Restsplain was created, existing documentation, uniqueness of sites
We’re big fans of documentation. We create all sorts of documentation, from inline documentation in PHP, to project readmes with the key information everyone needs, to internal project wikis.
Documentation can be problematic for one key reason: it can get out-of-date. This has been a problem since the early days of software, and continues to this day. To combat this problem, many developers have switched to using inline documentation, where the documentation lives with the code itself. With strong review policies, this means that docs are updated in lock-step with the code itself.
Inline documentation is generally used by static analysis, such as in documentation generators or IDEs. However, it can’t be easily used without access to the codebase, and can’t be used for more dynamic pieces. In particular, there’s no way of statically analysing the WordPress REST API, as plugins and themes can add additional data to the output. Each site has a unique set of plugins, giving each site a unique REST API that a single documentation site (like WordPress.org) can’t possibly cover.
Thankfully, this isn’t an unsolveable problem. The WordPress REST API is built around self-documentation through object schemas. This documentation comes directly from the codebase, and is functional: the docs are the code. This is all available in a machine-readable standard format called JSON Schema, and can be retrieved for any API endpoint with an OPTIONS request.
Say Hello to Restsplain
Restsplain takes the WordPress REST API’s documentation and generates a beautiful interface, integrating into your site. This allows your site to have always-current documentation for your unique API, with styling to match your site.
image of Restsplain UI
One other advantage of using the API directly rather than static analysis is we can use the API. That means we can have interactive documentation, allowing you to read about an endpoint and immediately try it out.
gif of sending API requests
Restsplain is not just built for automatic documentation. Every good documentation site includes both automated and manual content. Thankfully, we already have a great CMS at our fingertips for working on manual content. Restsplain adds an API documentation content type to your site, allowing you to write and edit manual documentation using a familiar workflow.
Using Restsplain
Talk about using Restsplain on a site, customisation opportunities, etc.
Using Restsplain is as easy as installing the plugin. Simply download the plugin from GitHub, upload it to your site and activate. You’ll now have your own unique WordPress REST API documentation at /api-docs/
Restsplain integrates directly with your theme (via wp_head() and wp_footer()), and includes all the CSS you regularly enqueue. This allows you to write custom styles to suit your site, and tweak Restsplain’s design to exactly what you want.
You can also configure the logo, documentation URL, code highlighting, and more with filters.
Challenges
Talk about how Restsplain was built, struggles with React, etc
Restsplain is built as a React single-page app, integrating into the frontend of your site. Using React allows us to provide a fast and interactive experience, giving users an API reference similar to an offline app like Dash. The interactive requests allow for live example data straight from the site.
Using React in a distributable WordPress plugin is still in the early days, and some workflows leave much to be desired. …
(We’re working on internal tooling and documentation to improve React-based plugins and themes, and hope to release them soon!)
…
Roadmap
Talk about future plans for Restsplain, usage on wordpress.org, etc
…
We’d love everyone to install Restsplain and give it a shot. Download the plugin and try it today!
Interested in working on amazing tools like Restsplain?
We are always hiring, and we’d love to hear from you. Our flexible working policy means you can fit your work around your other commitments, whether that’s your family life, your other life as a musician, or your love of travel. All employees enjoy benefits such as a 28 day minimum holiday policy, regular new equipment, and our annual company retreat. You’ll get to work with and learn from a supportive team of colleagues.
We encourage people of all backgrounds and locations to apply, and are committed to creating a diverse environment that every team member feels proud to be a part of.
