Draft API Specification

Technical
1

Draft API Specification

As we are moving to an API first approach for HSDS we need to specify what a minimal API should look like. We also need to define some methods that, even if they are not required, should be consistent amongst publishers of this API.

The document Por11328 - Aligning Open Referral and Open Referral UK - The API - HSDA contains work as an approach to the API. All sections in this document from 1 - 2.5 should be followed.

The following spreadsheet contains information on the endpoints that will be codified into an OpenAPI specification:

HSDS API Endpoint Detail

Aspects of the above spreadsheet differ from what has been previously discussed and may need to be discussed further:

MUST, SHOULD, COULD.

Each endpoint and parameter has a must, could or should related to it (column C). The opinions about what things fit into these categories might be implementation specific and there might be disagreement about what minimally should fit in each category.

We invite people to share their views by adding comments directly to the spreadsheet. To do this, right click fields within the ‘API Required’ column (Column C) and add a comment for us to review.

“full” parameter.

Service list by default will contain relationships that are only one-to-one with it. This option gives you the possibility in certain publications to ask for the full nested JSON object.

organization/{id} by default only contains minimal service information

This is so that publications that have organizations containing lots of services will not need to provide all the related full nested service information at once. This is because services in organizations can not be paginated and may mean the response size is too big.

A parameter full_service has been added to be able to ask for that information on publications that wish to support it.

Not many detailed search parameters

Things like location/age range search are not currently part of core spec. However, these and other paramenters may be adopted into the core spec in the future to allow further interoperability.

An optional New Line Delimited JSON endpoint for services.

Pagination is easy to implement and should be the default but has downsides of not ensuring consistency when paginating through large amounts of data if the data is changing while paginating. Streaming all the data using NDJSON is a solution to this as the provider streams all data that is consistent at one point in time. This will not be for all publications but useful for ones that care about consistent reconciliation/federation.

Recommendations

From doing this work we’ve identified that the following things would be very beneficial as a part of the core spec. Both have been discussed previously, but not yet decided for 3.0:

UUIDs

All IDs should be UUIDs to help with reconciliation and federation. We previously said that we did not want to break backwards compatibility to do this, but as we are now moving to an API approach, specifying this now would be a great benefit.

Last Modified Dates for Services.

An optional “last_modified” datetime field against a service that changed when a service and ANY related data changed, would be very good to add before 3.0. It would give the service endpoints a way to say they only wanted changes from a certain point.

We are proposing the addition of these as a part of the 3.0 upgrade and would welcome people’s views on this also.

Please share your comments and feedback by replying to this post.

For those in the HSDS workgroup. I will send an email out shortly inviting you to a workgroup meeting to discuss this as a collective next Monday (13th Feb)

Thanks to @davidraznick for his hard work on this.

Dan

2

Both recommendations sound like good ones to me.

Excited to see this progress and I appreciate your IMO very clear email. :slight_smile:

1 Like
3

I think with the UUID we need to specify that it should be lowercase. While this is the standard some UUID generators output characters as upper case.

2 Likes
4

We can add an additional REGEX validation to the jsonschema as I think the default UUID format does allow upper case as it conforms this spec RFC 4122 - A Universally Unique IDentifier (UUID) URN Namespace

5

Great work @davidraznick and @Dan-ODS :clap:

I’ve added a few comments to HSDS API Endpoint Detail , the main suggestions being:

  • accept Shelby’s prior suggestion of changing the “text” parameter to “search”. Leave it to individual implementations as to how full or sophisticated they make this
  • make the “full” parameter a COULD because this can place a heavy lead on servers and give publishers a further excuse not to make their API feeds open
  • make service_at_locations a SHOULD because prior feedback from the workgroup requested it. This is supported by UK people wanting to show on a map only those locations that are close by for a service which has many locations
  • consider a “post/zip code” (or something else specifying a geographical point) parameter and a “proximity” parameter for service_at_locations so implementations can filter to nearby locations (and ones that fall within a service_area). This could be left to 3.01 but I think it is the main reason for having service_at_locations
  • consider “top_only” and “parent_term” parameters for taxonomy_terms. In the UK these never made it to our Swagger pages but we found our query tool needed them to drill down through hierarchical taxonomies.

Other points:

  1. You and I discussed specifying that the stub (or “base”) URL should give the HSDS and profile versions that the feed complies with. It could also return other metadata on the feed. Might you suggest something?
  2. Have you somewhere defined what a header looks like for listing endpoints before the array of items? In Por11328 - Aligning Open Referral and Open Referral UK - The API - HSDA, Shelby has some comments and suggestions that I think we should follow.
  3. Yes, we can leave other parameter, such as those for age and schedule until a later release, but some guidance on naming these might help to avoid deviation in implementations that’s hard to put right later
  4. My draft suggested “UK compliance” page will include the MUSTs and some SHOULDs. Of course we should discuss this with impklementeers of teh current UK API. I’m glad you’ve stuck to that in most cases

Mike

1 Like
6

Hi all,

The HSDS API Endpoint Detail has been updated based on feedback from the last workgroup meeting.

New Root Endpoint

When querying a particular API publication there at its root ‘/’ endpoint which MUST be supplied with the following properties:

Property Type Required Description
version string True HSDS version of this API
profile uri False URL of the information on the HSDS profile of this API. Not needed if using HSDS.
openapi_url uri True URL of the openapi JSON file which defines this API

All endpoints except /services, /services.json and / are OPTIONAL

No COULD or SHOULD, just OPTIONAL endpoints and parameters. COULD and SHOULD can be defined by profiles in future.

“minimal” Parameter on Service, Services.ndjson

Return a list of services with just service id and last_modified date. This endpoint should return ALL relevant services in a single page.

“modified_after” Parameter on Service, Services.ndjson and Service at Location

A datetime that the returned services have their last_modified field after. Should be in rfc3339 with a millisecond fractional component.

If you have any further comments or feedback please respond to via this thread.

Thanks,

Dan