RFC0014: Summary resource #27
Conversation
Signed-off-by: Arnau Siches <arnau.siches@digital.cabinet-office.gov.uk>
content/summary-resource/index.md
Outdated
| |`custodian`| Optional String |The custodian of the register.| | ||
| |`description`| Optional String |The description of the register.| | ||
| |`hashing-algorithm`| [HashingAlgorithm](#hahing-algorithm-attributes) |The hahing algorithm used throught the register.| | ||
| |`last-updated`| Timestamp |The date the register was last updated.| |
There was a problem hiding this comment.
Is it worth defining the time format of last-updated e.g. is it a Timestamp according to: https://openregister.github.io/specification/#timestamp-datatype ?
There was a problem hiding this comment.
Sorry, yes all types are defined according to the spec.
There was a problem hiding this comment.
This means that "String" is a string as defined by the specification too.
| GET /summary | ||
| ``` | ||
|
|
||
| ### Response attributes |
There was a problem hiding this comment.
would we want to include the root hash in this response?
Signed-off-by: Arnau Siches <arnau.siches@digital.cabinet-office.gov.uk>
There was a problem hiding this comment.
I think there are two parts to this RFC - adding the new object and renaming the endpoint.
Adding the hashing-algorithm object makes sense, but I'm not enthusiastic about renaming the endpoint right now. Summary is slightly better but it still doesn't communicate to me what the endpoint is for, and it doesn't outweigh the inconvenience of a breaking change. Ideally I would like us to version the APIs and have a clear policy about how we deprecate APIs, but maybe this is a topic for another RFC.
The best name for this thing depends on what the intended use cases are for this endpoint and whether we have any plans to extend it.
For example, as an API user I imagine I will want some way to retrieve metadata about the current schema, once that is available (not necessarily the full log of schema changes). At the moment it seems like you have to know about the register/datatype/field registers to do this (this is how the MOJ client does it) but this could potentially be returned from this endppoint.
If we are likely to change what this returns or create similar endpoints, then I'd prefer to postpone the name change until we've thought about it a bit more, but I'm happy with either approach. 🤔
| |`hashing-algorithm`| [HashingAlgorithm](#hahing-algorithm-attributes) |The hahing algorithm used throught the register.| | ||
| |`root-hash`| Hash | The Merkle tree root hash. | | ||
| |`last-updated`| Timestamp |The date the register was last updated.| | ||
| |`licence`| String |The licence of the data.| |
There was a problem hiding this comment.
What is a valid string for this? Should we require an OGL or other open source licence?
There was a problem hiding this comment.
I think we can't afford to be restrictive here. OGL is one of many and these things change too often to be prescriptive at the spec level.
There was a problem hiding this comment.
Just wondering if there's a way we can encourage some canonical naming so we don't end up with a bunch of registers using different variations of the same licence name.
There was a problem hiding this comment.
We could add a non-normative section in the spec suggesting something on the lines of https://help.github.com/articles/licensing-a-repository/#searching-github-by-license-type
Or, we could consider having a register for known licenses. I'm not a 100% on board with this one because the custodianship model applied to this but it would be a very useful register to have. What do you think?
There was a problem hiding this comment.
Something like that list would help I think.
I don't know if it should be register, but maybe the open standards team could comment on that. I think it would be useful if someone ever builds a catalog of reusable software/data across government, like code.gov
There was a problem hiding this comment.
This seems like a good list to base our restrictions https://spdx.org/licenses/
There was a problem hiding this comment.
Mentioned in here co-cddo/open-standards#31
There was a problem hiding this comment.
Cool - I think a non-normative recommendation to use their identifiers would address my concern above.
Agree
The version strategy deserves an RFC on its own and it is likely to be a piece of work aside from the current Q2 one. Regarding the rename, it's a soft change given that we can redirect 301 users but I'm happy to hold on this renaming and discuss it another time.
Not plans per se, it might need evolution but none I can foresee right now.
See #28 The schema is distinct from the summary on purpose. |
|
I'm rejecting this RFC in favour of RFC0018 (#31) |
Context
The current summary is exposed as the register resource (
GET /register).The name of the resource is misleading as you don't get the register, only
some metadata about it. Also, the current specification and implementation
don't agree on what is the register resource.
Changes proposed in this pull request
This RFC proposes a summary resource to offer an overview of the current state
of the register.
Guidance to review
It should make sense as an independent resource and potentially an embeddable resource in paginated resources (probably non-normative).