I just published the OpenAPI Spec I just created for the Human Services Data Specification (HSDS) into one of my default portals, which once the OpenAPI Spec is indexed via the portals API.json, I get a ready to go landing page, documentation, and other tooling for supporting the API. I have been pushing forward my API documentation, beyond the (now) standard issue Swagger UI, keeping the OpenAPI Spec core, but evolving the UI portion using Jekyll and Liquid.
I have a default API docs implementation, which loops through all OpenAPI Spec included within a project, and renders HTML documentation for each path, verb, etc. I’m still working on how I recreate the dynamic functionality brought to the table by Swagger UI, but so far I’m really, really enjoying the flexiblity with the user interface, and overall experience I get using this approach–I know the interactive portion will come.
One of the things I’m enjoying being able to do, is apply additional, external elements to the OpenAPI Spec, by augmenting them with independent, APIs.json defined schema. One example of this I am calling API filters, a simple filter collection defined in both YAML and JSON, that is indexed along with the OpenAPI Spec, within the APIs.json index. For the Open Referral API I wanted to provide the complete documentation, but also play around with other different, filtered views of the API – designed for specific audiences.
The first entry I made into API filters, I called “learn the basics”, only showing the core resources that were available via the Open Referral API, eliminating all of the noise.
Open Referral API - Learn the Basics
Categories
Get all categories
/categories
GET
Contacts
Get Contacts
/contacts
GET
Create New Contact
/contacts
POST
Locations
Get Locations
/locations
GET
Add Location
/locations
POST
Metadata
Get Metadata
/metadata
GET
Add New Metadata
/metadata
POST
Organizations
Get Locations
/organizations
GET
Create a new organization
/organizations
POST
Search
Get locations that match certain criteria.
/search
GET
Services
Get Services
/services
GET
Create New Service
/services
POST
This API docs view, gives me just the handful of core endpoints, filtering out the other 60+ APIs that someone who is just learning about the Open Referral API do not need to be bothered with when they are learning. Next, I wanted to focus in on a specific area of the API, like services, and only show the summary elements, that most people will care about when it comes to these services. I’m calling this one “services summary”:
Open Referral API - Services Summary
Services
Get Services
/services
GET
Create New Service
/services
POST
Service - Categories
Update a service’s categories
/services/:service_id/categories
PUT
Service - Contacts
Get Contacts
/services/:service_id/contacts
GET
Add Contact
/services/:service_id/contacts
POST
Service - Eligibility
Get Eligibility
/services/:service_id/eligibility/
GET
Add Eligibility
/services/:service_id/eligibility/
POST
Service - Fees
Get Fees
/services/:service_id/fees/
GET
Add Fees
/services/:service_id/fees/
POST
Service - Funding
Get Funding
/services/:service_id/funding/
GET
Add Funding
/services/:service_id/funding/
POST
Service - Holiday Schedule
Get Holiday Schedule
/services/:service_id/holiday_schedule/
GET
Add Holiday Schedule
/services/:service_id/holiday_schedule/
POST
Service - Interpretation Services
Get Interpretation Services
/services/:service_id/intepretation_services/
GET
Add Interpretation Services
/services/:service_id/intepretation_services/
POST
Service - Languages
Get Languages
/services/:service_id/languages/
GET
Add Languages
/services/:service_id/languages/
POST
Service - Payment Accepted
Get Payment Accepted
/services/:service_id/payment_accepted/
GET
Add Payment Accepted
/services/:service_id/payment_accepted/
POST
Service - Phones
Get Phones
/services/:service_id/phones
GET
Add Phone
/services/:service_id/phones
POST
Service - Regular Schedule
Get Regular Schedule
/services/:service_id/regular_schedule
GET
Add Regular Schedule
/services/:service_id/regular_schedule
POST
Service - Required Document
Get Required Document
/services/:service_id/required_document/
GET
Add Required Document
/services/:service_id/required_document/
POST
Service - Areas
Get Service Area
/services/:service_id/service_area/
GET
Add Service Area
/services/:service_id/service_area/
POST
The Liquid driven HTML API docs are the same for the full documentation, for learn the basics, or for the services summary. All three documentation elements are also all driven from the same OpenAPI Spec. The only thing I did, was specify one of the API Filters by name, in the top of each specialized docs page – the Liquid template handles the rest. Its still pretty crude, and I’m sure it will need a lot of polishing, but it provides me with a simple, machine readable way to filter out the endpoints I do not need, accomplishing what I set out to do.
I am using schema approaches like this more lately. An approach that when indexed along with the OpenAPI Spec, in an API.json file gives me other layers, and dimension that I can apply for not just documentation, but almost any other stop along the life cycle. To me, and important part of this is that these elements do not live embedded within the OpenAPI Spec, living independent of the the machine readable definition of the API. Each one lives its own schema file, and when indexed alongside each API definition, within the APIs.json, interesting things happen–all without cluttering up the OpenAPI Spec, keeping it purely about the API.
My goal in this work, is to provide me with a way that I can equip the other less technical advocates for the Open Referral format, with a toolbox of documentation, visualizations, and other snippets that will help them articulate what the API can do. Since all of these API documentation snippets are APIs.json, and OpenAPI Spec driven, using Liquid, and Jekyll to render, they are something that anyone could put to use, for any API.
