The API and a definition of the core simple/verbose schema on endpoints

Technical
1

Hi there

I am new to the community and am looking to implement an OR compliant feed for the DfE. I have a question around the definition of the schemas passed between services, NOT the db schema design.

Ita a question of verbose and simple schemas and have a core base schema that is extensible for the API.

I was hoping someone could point me in the direction of these schemas as I cant find a definitive simple / verbose schema in the swagger yml for each endpoint? For example getting a service list could bring back a list of simple schemas and fetching by identifier could send back the verbose.

And building on that perhaps allows the API to control what schemas it requests?

Am looking to do a PR on the API and schema on github, but please let me know if I am completly off base in my understanding?

Many thanks

Richard

1 Like
2

Hi Richard,

Welcome to the forum and thanks for your query. I think @davidraznick would be the person to respond to this. He’s is on Wednesday so will check-in with him on this then and we’ll get back to you.

Dan

3

Hello Richard and thank you for posting here.

I normally refer people to the Swagger pages, but if they don’t give you what you want, then @davidraznick is the person to help. He is working on the updgrade to Human Services Data Standard (HSDS) 3.0 with its UK profile which will bring small changes (nothing big) from the current Open Referral UK standard.

David’s JSON schemas are here. He’ll be able to explain more.

1 Like
4

Thanks @MikeThacker Apologies for the delay I have been unwell for a few days.

I think where I am confused is the mapping of endpoint to the schemas they require.

I was expecting something along the lines of

/services (returns a default simple schema)
/services?return_type=verbose | simple

I see some of the listed communities that adhere to the framework pass back different schemas on the services GET endpoint and wondered if assigning a schema to each endpoint would suffice?

I may completely be missing something tho so please bear with me! Is the convention that the /services endpoint returns the simple schema and the /service/id endpoint returns the verbose?

Is there a complete swagger definition somewhere as I think that link you sent has example data but no specific schema assigned to the endpoints in the definition

Like I said, I am knew to open referral but have done a lot of API specification in pervious roles so anywhere I can help alongside moving the public sector forward I would be more than happy :pray:

5

@rgparkins

Hello

We are soon going to be updating to HSDS 3.0, so I think this might be causing some confusion.

The latest openapi specification can be found here.

We also have a documentation page: http://docs.openreferral.org/en/3.0-dev/hsds/api_reference.html built off this schema with examples. We will also be linking to the schemas themselves there too.

All data schemas (not the pagination parts) that is referenced in the openapi specification can be found in schemas and compiled schemas.

Yes, the listing endpoint have (by default) a full schema and for /services/id and a limited version for /services. There are also options, as you said, named full and minimal, for the listing endpoint.

Hope that helps and you are feeling better.

6

@rgparkins

We now have a Swagger UI version of HSDS 3.0 available if that is more useful.

1 Like
7

Thanks @davidraznick that really helps… So just for my understanding… If I give examples here of the endpoints I am confused about, that i THINK you are saying could be fixed by the upgrade in version of the standard… If seems that Bristol and Buckinghamshire validate against the spec BUT their services endpoint brings back different schema and I have no way of telling the API I want simple of verbose data coming back on these endpoints, and some dont filter either

https://elmbridge.openplace.directory/o/ServiceDirectoryService/v2/services
https://bristol.openplace.directory/o/ServiceDirectoryService/v2/services

These bring back some common data but some endpoints are more verbose than others, for example Elmbridge brings back what seems like a simple service schema, meaning I make more calls to their other endpoints for details on locations etc etc but bristol brings back a lot more info

Just trying to gain some context on whether this is expected as within our code we will need to start looking at complex mapping routines for each LA which will make the job a lot more difficult and was hoping the standard would have given us confidence in the data

I can only put 2 links in this post unfortunately

Apologies if I am misunderstanding the spec :innocent:

Regards

8

It’s common to have different levels of detail in the responses returned by API endpoints. Simple schemas might include only essential information, while verbose schemas might include additional details or nested objects. This can be useful for optimizing network bandwidth and improving performance.

9

Yes @infohills. This is the approach we have taken with lists of items (e.g./services?..) just including basic information and queries on individual items (e.g. /services/{id}) expecting full verbose information.

Many fields/properties remain optional (although that changes between profiles) so some might be missing or have null values.