My Developer Portal Checklist For A Human Services API

02 Mar 2017

I was handed the URL for a human services API implementation for Miami. It was my job to now deploy a portal, documentation, and other supporting resources for the API implementation. This project is part of the work I'm doing with Open Referral to help push forward the API conversation around the human services data specification (HSDS).

DocumentationNow for the documentation, the most important piece of the puzzle. I published a Liquid documentation driven by the OpenAPI for the API. With a little bit of JavaScript voodoo, I was able to make the documentation interactive so that you can actually try out each path, and see the JSON response--the documentation is driven by the APIs.json and the OpenAPI for the API.

Status PageBeyond the resources to get up and running with documentation, code samples, and a road map, issues, and change log to stay in tune with the platform, I wanted a status page keeping an eye on things. I signed up for a monitoring service called API Science (which I highly recommend), and imported the OpenAPI definition, and had monitors to keep an eye on things and make sure the API stays up. The page is generated from an embeddable JavaScript widget and is updated using the API Science API.

GithubThis developer portal runs 100% on Github and leverages the potential of Jekyll when running on Github. The API is hosted on Heroku and run by someone else, but the developer portal is a static website, completely editable via Github through the web interface, API, or locally with the desktop client. Github also provides much of the support framework for the project, driving the roadmap, issues, change log, and 1/3 of the support options for developers--the entire site is driven from the _data store, with the website just being a Liquid-driven Jekyll template.

OpenAPIThis developer portal is defined by its OpenAPI definition. It drives the documentation, generated the code samples, fired up the API Science monitors, and is the central contract defining the APIs operation. I will be keeping the OpenAPI up to date, and using it as the central truth for the API and its operations.

APIs.jsonThe portal is entirely indexed using APIs.json, providing a single machine-readable definition of the API and its operations. All the supporting pages of the API are linked to in the index, and their contents and data are all machine-readable YAML and JSON. The APIs.json provides access to the OpenAPI which describes the surface area of the API, as well as providing links to all it's supporting operations.

What Is Next?I'm going to put things down for a couple days. We still need some FAQs entered, and the content needs fluffing up and editing. Then we'll invite other folks to take a look at. Then I will get to work on the POST, PUT, PATCH, and DELETE paths, and once those are certified I will push as part of the OpenAPI, regenerate the code samples, and turn on the ability for people to get involved not just reading data, but also potentially adding and updating data in the database--making things a group effort.

I'm going to take what I have here, and fork it into a new project, making it a baseline demo portal for Open Referral. My goal is to have a downloadable, forkable API portal that is well documented, and anyone providing an HSDS compliant API can put to use for their project. I just wanted to take a moment and gather my thoughts on what I did and share the approach I took with you.