Version 1.1 of the Human Services Data API Specification

[This post is from Kin Lane, the API Evangelist, who is serving as Open Referral’s deputized Technical Lead for our OpenAPI specification project. Thanks Kin!]

Version 1.1 of the Human Services Data API specification (HSDA 1.1) is now available for review and comment.

This is an alpha implementation of our OpenAPI specification. It is built upon version 1.1 of Open Referral’s Human Services Data Specification (HSDS). Whereas HSDS is designed to enable bulk packaging of resource directory data, the HSDA serves as a common protocol for resource directory APIs.

To facilitate testing, we’ve made the HSDA available in this demonstration portal (see a screenshot below). This portal is a redeployable (and forkable) reference implementation that provides guidance for working with the HSDA protocols. Implementers can use it to easily set up a “developers’ area” for their own API implementation.

Moving forward, we’ll collect feedback from stakeholders and reiterate this process twice more over the course of the summer. We’re setting a day/time for the next Open Referral Assembly videochat now; if you’re interested in participating, indicate your availability here.

Details about the HSDA and our development process:

Picking up where HSDS 1.1 ended up (more on that here), our OpenAPI specification is informed by a range of actual API implementations from across the Open Referral network.

As our Project Charter explains, we have a ‘working group’ of implementers (referral software vendors and other developers) who have agreed to share their schema, bring actual users to the table to consult with us, and — assuming success — adopt the resulting specification in their own APIs. Dialogue with this group helps us learn from the existing and emerging practices in the field.

So far, we have collaboratively identified four ‘types of use’ for which resource directory APIs should be developed:

• Software development — using APIs to build tools that connect people to services and/or otherwise channel resource data to end-users.
• Resource database administration — using APIs in the process of collecting, updating, and verifying data that might be shared across distributed systems.
• Research — using an API to pull bulk or specific sets of resource data for analysis.
• Provider Self-updating — for service providers who want to update information about their own services.

In future rounds of feedback, testing, and reiteration, we will assess the API model according to these perspectives.

On the API Evangelist blog, I’ve posted a longer explanation of the design principles and operational considerations that I applied in this process.

Our Demonstration Portal and Validation Tool

The Open Referral API portal is a live working demo of the Human Services API specification, written in PHP, running on Linux, and using MySQL as a database. It’s not designed to be a production instance, but if you’d like to explore it as a specific implementation, please feel free to reach out. The portal itself (not the API) runs on Github, and is forkable. (In fact, we are using it as the testing environment for the Miami Open211 implementation.)

We’re also pleased to see that one of the volunteers in our community, Chris Spiliotopoulos, has developed a data validation tool: the Open Referral playground. You can use the playground to explore the Open Referral schema and test CSV files for compliance with HSDS. We hope this tool is useful for implementers who are working with HSDS and HSDA, and will aim to round up a future version into the Open Referral Github organization. Thanks Chris!

What Is Next?

We’ve already identified some important candidate features that may be included in HSDA v1.2, like allowing for schema filtering (being able to select how much or how little of the information you’d like to receive about organizations, locations, and searches). Please visit the Github repository for the Human Services Data API specification to stay up to speed on which features will be included in v1.2, v1.3, and beyond.

We are also working on completing a JSON Schema validator for the API specification, which will allow individual implementations to validate their API and underlying schema.

For the next 4 weeks, we welcome your feedback on version 1.1. We’ll actively conduct a ‘peer review’ process with the help of the Open Data Services Cooperative (who stewarded the most recent iteration of HSDS).

In advance of version 1.2, we’ll host a videochat Assembly to discuss issues in real-time; if you would like to participate, please indicate your availability in this schedule survey here.

This entire cycle will be iterated once more this summer — with an anticipated release of HSDA v1.3 by September. At that point, we expect to set the spec for now while reporting out a high-level ‘wishlist’ and ‘roadmap’ for the path to version 2.0.

Open Referral Is A Community Initiative

All of this work is made possible by the Open Referral community. We are always looking for more help in designing, developing, testing, and participating in the conversation around each iteration of the specification. We welcome contributions from developers and subject matter experts who can help evolve the schema, API specification, and the emerging set of tools that work with each.

Many thanks to the participants who have informed this iteration, including: Shelby Switzer at Healthify; Neil McKechnie at iCarol; Benj Kamm at Health Leads; Doug Zimmerman at VisionLink; Taylor Justice and Michael De Lorenzo at Unite Us; Andrew Benson at Ontario 2-1-1; Dave Erlandson at United Way / 2-1-1 in Minnesota; Kate Lambacher at CIOC; and Clive Jones at the Alliance of Information and Referral Systems (AIRS).

Also thanks to AIRS for fiscally sponsoring this initiative and providing subject matter expertise.

Finally, thanks to the Digital Impact program at Stanford’s Digital Society Lab for making this development cycle possible.