Metadata

[kinlane]

I would also recommend holding off on the API for the metadata portion of the schema - https://openreferral.readthedocs.io/en/latest/reference/#metadata

This area needs some additional considering when it comes to managment, logging, and other aspects of API operations.

[nplumley]

It seems to me that explicit CREATE / UPDATE / DELETE operations for metadata are not needed and that implication is that these records should be created and updated simply as a side effect of creating and updating any of the core records (service, location, etc)

[kinlane]

Agreed. I'm exploring additional usage scenarios where external, out of moment updates, but at this point it's imaginary, and not actual real world usage based community feedback--awaiting real feedback to make a recommendation.

[NeilMcKLogic]

I can imagine use cases where this metadata would be very important, like synchronizing two or more different databases that may be sporadically disconnected. If it needs to be deferred due to time constraints, so be it, but it should stay on our radar.

[timgdavies]

I can see the case for being able pull meta-data about a record (GET)

@NeilMcKechnie do you envisage cases where in synchronization one database would need to push a change history to another?

[kinlane]

This has become it's own project in context of HSDA, I'm labeling as HSDA meta. I will be thinking of in context of HSDA management -- following best practices from API management industry.

Allowing for API service composition, and transactional based approaches to tracking on meta data.

More to come as this project is flushed out.

[timgdavies]

Is another option here to 'bring back' the metadata table in HSDS (it was in the early spec, and still around, but I've not seen it in-use) with a foreign_key for each kind of entity that might have meta-data attached.

In that case, a '/full' or '/complete' representation of any object could include a 'meta' block, or resources like /service/{service-id}/meta could be available just like /services/{service-id}/phones would be?

[kinlane]

Interesting feedback. I've picked up the meta table work and begin moving forward in context of HSDA as it's own project, using to store not just the data change, but the paths, verbs, and users involved. (https://github.com/openreferral/api-specification/issues?q=is%3Aopen+is%3Aissue+label%3Ahsda-meta)

I like the concept of augmenting paths with /meta to provide a history. Look at weighing this as part of v1.3 for hsda, as well as how it works with hsda-meta road map.

[dsurrao]

Can metadata include user information, i.e., who made the API call? How is user information passed in a CREATE/UPDATE/DELETE transaction?

[kinlane]

yes, @dsurrao the new meta data structure now includes:

• id (string) | Each entry must have a unique identifier.
• timestamp (string) | The timestamp for entry (yyyy-mm-dd)
• appid (string) | The appid for entry.
• system (string) | The system for entry.
• path (string) | The path for entry.
• verb (string) | The verb for entry.
• request_parameters (string) | The parameters for entry.
• request_headers (string) | The header for entry.
• request_body (string) | The body for entry.
• response_body (string) | The body for entry.
• status (string) | The status of this entry (Complete, Waiting)

Which goes beyond HSDS to include HSDA relevant information as you ask for. appid is who made the call, and verb + path should give you details of transaction, pus the parameters, headers, and body should complete the picture.

https://openreferral.github.io/api-specification/hsda-meta/

[mrshll1001]

We will be archiving this repository soon. We're closing this issue because we believe it has been conclusively addressed as part of work on the main HSDS standard.

In this case, HSDS 3.0 has a Metadata object and we have provided guidance in the api specification for how API implementers can make sensible decisions about the level of metadata to include in responses