Upgrading the Human Service Data API protocols to 2.0

—

by

Kin Lane
in

[Ed: This post is from Kin Lane, author of initial Human Service Data API protocols, and now Chief Evangelist at Postman, an API development platform. Welcome back, Kin!]

Now that the Open Referral Initiative has upgraded to version 2 of the Human Service Data Specification (HSDS), we’re commencing a subsequent upgrade to version 2 of our Human Service Data API protocols (HSDA).

We now invite members of the Open Referral community to contribute feedback – especially use cases, specific feature requests, and example OpenAPI definitions – that can shape the iteration of these API protocols and, in turn, facilitate the emergence of interoperable, reliable resource directory information infrastructure.

For general purposes, we have put forth a starting point here in this HSDA 2.0 core specification proposal (documentation here). This is the primary object for which we request feedback: the HSDA 2.0 core spec provides separate OpenAPI definitions for each area of the specification, leveraging the YAML definition for each service as both a machine and human readable contract of what can be expected of each HSDA implementation.

Furthermore, we’re proposing the following complementary microservices for consideration during this current comment period:

The major changes being proposed in the HSDA v2.0 upgrade are as follows:

  • HSDS v2.0 Update: All of the schema brought up to date with version 2.0 of HSDS.
  • Standardized Querying: Standardized search across contacts, locations, organizations, and services, as well as for standardized search — the query standard is outlined here.
  • Header Pagination: Added a set of headers to each of the root level resources, showing the details of pagination for each query.
  • Status Codes: Status codes standardized across all responses, providing a consistent set of HTTP status codes for all API paths.
  • RFC 7807 for Errors: Standardized error responses for 4xx and 5xx errors, providing a common approach to reporting problems using RFC 7807 (Problem Details for HTTP APIs).

Our general principle for deciding what should be included in the core specification is that it should be able to work for the most basic users. Which is to say, a user shouldn’t have to write code to be able to use some feature of these API standards; they should be able to put a command into a URL, and get a CSV output. 

Open Referral is using the OpenAPI specification to describe the surface area of each of the HSDA services, providing a common human- and machine-readable definition for each of the services. If members of our community see different or additional ways that these protocols can better meet your needs, there are two primary methods by which we encourage engagement:

  1. Update OpenAPI – Update the existing OpenAPI for each of the services using the OpenAPI specification vocabulary, submitting proposed changes as a GitHub issue or as a pull request on the repository.
  2. Add OpenAPI Extension – Extend the OpenAPI specification by providing your own definition of the feature you are looking to add to HSDA. 

If you aren’t fluent in OpenAPI we recommend getting familiar with the specification. Over the last decade OpenAPI has become the defacto standard for defining HTTP APIs, and provides a common vocabulary and contract to describe every detail of what an API does or doesn’t do. Using OpenAPI helps ensure we are all speaking the same language when it comes to making sure HSDA supports your needs.

There are numerous ways you can get involved in defining HSDA:

We look forward to your feedback on the next version of the specification. Together, we will ensure that information about human service organizations, locations, and programs can be made more accessible, reliable, and interoperable – wherever and however people wish to use it.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *