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).
I got to work forking my minimum viable API portal definition, to provide a doorway for the Miami Open211 API. Next, I got to work on setting up a basic presence for the human services API. I started with giving the portal a title, and a basic description of what the service does, then I got to work on each of the portal elements that will help people put the data to work.
It can be hard to cut through what you need to get going with an API and cut through all the information available. The portal has a getting started page providing a basic introduction, a handful of links to the documentation, code, and where to get help--the page is driven from a YAML data store available in the _data folder for the repository.
I included an authentication page to make it clear that the API is publicly available, but also provide a placeholder to explain that we will be opening up write access to the organizations, locations, and services that are being made available--the page is driven from a YAML data store available in the _data folder for the repository.
Frequently Asked Questions
Next, I wanted to always have the most frequently asked questions front and center where anyone can find it. I am using this page as a default place to publish any questions asked via Github, Twitter, or email. The page is driven from a YAML data store available in the _data folder for the repository.
To help jumpstart integration, I also generated and published a Postman Collection, so that anyone can quickly import it into their client, and get to work playing with the API in their environment. You can do this with OpenAPI also, but Postman helps extend the possibilities--the Postman Collection is editable via its Github page.
Next, I published a road map so we could share what is next for the project, providing a list where developers can stay in tune with what is going to happen. The road map entries are pulled from the Github issues for any entry with the road map label. There is a script that can be run regularly to keep the issues in sync with the roadmap, and the page is driven from a YAML data store available in the _data folder for the repository.
Similar to the road map, I created a page for sharing any open Github issues, that are labeled 'issues', to help communicate outstanding and known issues with the platform. It stays in sync using the same script, and the page is driven from a YAML data store available in the _data folder for the repository.
In addition to a road map and known issues, when these items get accomplished or fixed they get moved to the change log, keeping a complete history of everything that has changed with the platform. It stays in sync using the same script, and the page is driven from a YAML data store available in the _data folder for the repository.
Terms of Service
For the terms of service, I just grabbed an open source copy from Wikidot, providing a baseline place to start when it comes to the TOS for the API-the terms of service is editable via its Github page.
The blog for the project is driven by the Jekyll framework for the developer portal hosted on Github Pages. To manage the blog entries, you just add or update pages in the _posts folder for the website. All entries in the _post folder are listed in chronological order on the blog page for the developer portal.
This 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.
This 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.
The 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.