Upgrading the Human Service Data API protocols to 2.0

Skip to first unread message

Greg Bloom

Jan 26, 2021, 9:45:32 AM1/26/21
to OpenReferral
Hi folks – sorry to send multiple messages in a row, but while I'm in your inbox already: 

We've begun the process of upgrading the Human Service Data API protocols to version 2.0, in accordance with last year's upgrade of HSDS to 2.0, and to address a range of issues that have emerged since the initial API protocols were established. Kin Lane, API Evangelist (now an executive officer at Postman) has once again resumed the helm for this process. 

Kin has already put forth a demo spec for 2.0, and we're requesting comment. In the blog post we identify a range of issues on which we're specifically seeking feedback, though I'm all ears for anything that might come up.

In particular, we're looking for technology developers with some experience in using APIs to publish and/or consume resource data. I'd also like to hear from anyone who conducts I&R and who has experience using tools that leverage resource data APIs – your insight could be very valuable.

I'll follow up in a bit to schedule opportunities to discuss in real-time. 

Let me know if you have any questions or suggestions!

Mike Thacker

Jan 26, 2021, 12:36:20 PM1/26/21
to Greg Bloom, OpenReferral
Hello Greg

My colleagues and I would like to be involved and ideally make some of our tools work with the HSDA/S 2.0 format as well as with the standard with UK extensions.

The specification is wide-ranging and I would be surprised if anyone supports all methods with all parameters. We've identified priorities as:
  • standardising the way objects are referenced in web method responses
  • being able to retrieve all services and full details of each such that /services queries can be used to transfer a full set of data
  • supporting a few specific queries/filters on services such that an independent "service finder" application can work with an API. Typically this means finding services:
    • of a specified service type (from named taxonomy)
    • meeting given eligibility criteria
    • available within a given radius of a given locations
    • by text search on name and description
These might then be extended from services to organizations and locations if there is demand.

I'm less convinced of the need for PUTs and POSTs and for the full gamut of query options for which the specification provides. Of course this depends on use-cases and I'd welcome understanding people's use-cases and what parts of the specification they need to implement .

Mike Thacker Porism
Tel / Signal / WhatsApp: +44  7976 295 784
Bon Marché Centre, 241–251 Ferndale Road, London, SW9 8BJ, England
mike.thacker@porism.com | porism.com

You received this message because you are subscribed to the Google Groups "OpenReferral" group.
To unsubscribe from this group and stop receiving emails from it, send an email to OpenReferral...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/OpenReferral/514a566f-2fa1-428b-9946-3f6670afae1bn%40googlegroups.com.

See our eCasework for casework management designed especially for councillors

Greg Bloom

Jan 26, 2021, 5:46:04 PM1/26/21
to Mike Thacker, OpenReferral, Kin Lane
Thanks, Mike! 

I'm cc'ing Kin, and we'll be sure to follow up. 

I'm anticipating that Kin's main response would be to welcome examples of your preferences in the format of an actual OpenAPI specification. Groups that can show their work using OpenAPI/Swagger will be speaking Kin's language, so to speak. 

(If you aren't quite technically able to express proposals in this technical format, I will work with you to make sure that your perspective is articulated and heard :)


Devin Balkind

Jan 26, 2021, 8:41:50 PM1/26/21
to OpenReferral
Big thank you to Kin for taking HSDA to 2.0!

100% agree with Mike's priorities. 

I'm a newbie when it comes to in-depth discussion of APIs but  can imagine a few more priorities:
* list of services based on organization attributes like  (ex. only show me services of organizations with where legal_status=government_agency)
* ability to get all data related to an organization: its organization record, services, contacts, locations,  schedules, phones, etc all in one big JSON file. 
* ability to get all data related to a single service including its contacts, locations, schedules, phones, etc all in one big JSON file.

One reason I'd like all data related to an organization or services as a json file is that I'd like to then be able to diff that file against a previous version of it (for revision management) or a different entry for the same organization or service (for deduping data and merging data from multiple sources.)

Kin Lane

Mar 1, 2021, 1:58:16 PM3/1/21
to Greg Bloom, Mike Thacker, OpenReferral
Hello there Mike,

Happy to coordinate on any of the endpoints -- sounds like you are just looking to focus on the core resources (which are 3 paths):


We don't expect folks to adopt 100% of the spec, so I'd be curious to hear more about why you feel that it is implied? So we can shift the language, or as we are exploring how to better communicate all depths of the spec.

Our mission is to make sure the entire spec is available as a simple CSV download, and updatable (POST, PUT, DELETE) without having to work with the entire schema. Ie. just a list of phone numbers for an organization, or list of addresses for a service.

Please share any OpenAPI for the endpoints you care about most and we can do a diff on the request and response structure for each one to find the most compatibility possible.
Reply all
Reply to author
0 new messages