mrshll1001
commented
9 months ago I'm tentatively closing this since the HSDS 3.0 API Specification has moved on quite a bit from the HSDA days. @PorismDominicSkinner, please reopen this and let us know if your concerns are still valid re the new API Specification
I have been implementing the Open Referral API and would like to question the approach taken in the HSDA Specification to returning objects. For example, as single /services/{id} request returns the fields for a service plus the ids of any related objects. So, for example https://api.miami211.openreferral.org/swagger-ui/#/default/servicesIdGetService returns a service with id “1” for an organization. A further request is needed to describe the organization eg https://api.miami211.openreferral.org/index.php/organizations/1.
A “complete” query returns full embedded objects associated with a service, eg https://api.miami211.openreferral.org/index.php/services/complete/1 but it duplicates foreign keys in the embedded objects.
Our initial approach has been: To return full embedded objects for a single entity, eg https://api.porism.com/ServiceDirectoryService/services/10ca0354-90a0-42d9-a8d3-41453a88d3f4 To return, just properties and many to one’s for multiple entities, eg https://api.porism.com/ServiceDirectoryService/services/ To optionally include extra entities with a /include parameter eg https://api.porism.com/ServiceDirectoryService/services?include=name&include=description&include=service_at_locations
Before we make changes to our approach (see our Swagger), please can we confirm that the HSDA approach is correct and we should accept the duplication and the “all or nothing” approach to including details of embedded objects.