Upgrading the Human Service Data API protocols to 2.0
13 views
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!
greg
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 .
Thanks
Mike
 | 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 :)
~greg
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):
/organizations
/locations
/services
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
Forward
0 new messages