I was handed the URL for a human services API implementation for Miami. It was my job to 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.

Getting Started

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.

Authentication

I included an authentication page to make it clear that the API is publicly available and to 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 could 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.

Documentation

Now 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.

Code Samples

After completing the OpenAPI definition for the API documentation, I used the machine-readable definition to generate code samples using swagger code-gen. I published C#, Go, Java, JavaScript, PHP, Python, and Ruby code samples to help developers get started with their projects. All the language samples are published to a separate GitHub repository and the page is driven from a YAML data store available in the _data folder for the repository.

Postman Collection

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.

Roadmap

Next, I published a roadmap so that 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 roadmap entries are pulled from the GitHub issues for any entry with the roadmap 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.

Change Log

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.

Status Page

Beyond 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.

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 are editable via its GitHub page.

GitHub

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 one-third of the support options for developer — the entire store is driven by data from the _data store, with the website just being a Liquid-driven Jekyll template.

OpenAPI

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

APIs.json

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's 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 it. Then, I will get to work on the POST, PUT, PATCH, and DELETE paths. 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 that 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.