Rules for the core and extended standard API (HSDA)

At the request of the Workgroup, I’ve extensively modified the document Por11328 - Aligning Open Referral and Open Referral UK - The API - HSDA.

The document proposes:

  • rules for going from the full data structure or an application profile to API responses
  • core and extended web methods and their parameters
  • what should be excluded from the API standard and left to individual implementations

Comments can be added to the document and issues can be raised here for discussion.

In general the proposals are far less wide-ranging than the prior (international) HSDA which was not widely adopted. Subject to separate discussion I envisage Open Referral hosting a set of tools that will work with any compliant API endpoint (like UK tools do now).

Hello. I have been working with Devin for ORDirectory project available here - https://dcnext.sarapis.org/
Here are couple comments came from our experience there

HSDS 3.0

  • tables phone, contact, schedule, funding, language each has multiple relation fields like location_id, service_id, organization_id, contact_id, service_at_location_id. For unambiqous interpretation it may be reasonable to implement the rule that only one relation field can be filled or change multiple such fields to just two: relation_type and relation_id.
    We had real case when we needed to import into our system csv dataset exported by another developer from another app. It took efforts and bunch of time to correctly interpret relations and reintegrate whole dataset.

API structure

  • All-in-one List methods

Sort of this called /services/complete in previous HSDA
This is maintained by ORUK
And it looks to me (please correct me if I am wrong) you try to remove this in Por doc. I can guess that from this phrase “A “content” attribute will present the list as an array with each property conforming to the JSON schema generated to match the tabular data structure of the corresponding table/fields (e.g. the “service” table) in the HSDS/application profile version.
Any many-to-one relationships to the records (e.g. the one organization that might be associated with one or more services) being listed will be included as objects with properties conforming to the JSON schema generated to match the tabular data structure of the corresponding table/fields (e.g. the “organization” table) in the HSDS/application profile version.”

It is important that extended all-in-one response structure is maintained and it should return all related fields. Otherwise lists or search operations will get all slow. This exactly matches our last issue on DC Next where to speed up building search results page I needed to implement extended API method which returned additional fields but it broke previous HSDA specification.

  • Looks like typos:
  • taxonomy_term{id} seems should be taxonomy_term/{id}
  • taxonomies{id} seems should be taxonomies/{id}

Thank you

it may be reasonable to implement the rule that only one relation field can be filled or change multiple such fields to just two: relation_type and relation_id.

That makes sense @Maxim. I believe that in the UK we constrained HSDS so that phone, contact, schedule, etc could only belong to a service or a contact or an organization - normally a service in our case.

It might be sensible to say only one relation is allowed per record. What do others think? @robredpath can we support such a rule in JSON schema?

@Maxim you’re right that the proposals in Por11328 - Aligning Open Referral and Open Referral UK - The API - HSDA do not include /services/complete

I am concerned that such a method implemented in a completely open API would put a lot of demand on a server. Paginating results would help. So would throttling of web requests. Of course you can argue that retrieving a list of services and then cycling through every service in that list also puts a lot of demand on a server, albeit in smaller portions.

Would you (and others) be comfortable providing a /services/complete at an open API endpoint? If so, I’d suggest we consider it as an “extended web method”

I’ve fixed the two typos you spotted. Thanks very much.

@MikeThacker I agree such a method in open API could load a server significantly. And indeed paginating results would help.

I also thought we can control the amount of data returned through the parameter include which could allow to say return locations and physical addresses but exclude contacts and schedules from results. If so would that work to make it required?

Anyway without such /services/complete like method we will have to make 21 API requests to build search results page for 20 services. This probably would not load the server that much but will happen too slow

We can! JSON Schema has oneOf and anyOf keywords for this kind of thing.

Great conversation everyone. Where have we landed on the issues Maxim has brought up here?

1 Like