RFC0014: Summary resource #27
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| --- | ||
| rfc: 0014 | ||
| start_date: 2018-08-13 | ||
| pr: | ||
| status: draft | ||
| --- | ||
|
|
||
| # Summary resource | ||
|
|
||
| ## Summary | ||
|
|
||
| This RFC proposes a summary resource to offer an overview of the current state | ||
| of the register. | ||
|
|
||
| Dependencies: | ||
|
|
||
| * [RFC0013: Multihash](https://github.com/openregister/registers-rfcs/pull/26) | ||
|
|
||
|
|
||
| ## Motivation | ||
|
|
||
| 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. | ||
|
|
||
| ## Explanation | ||
|
|
||
| The summary resource is a new resource that will replace the old register | ||
| resource. The summary resource will not contain any information about fields | ||
| as this will be addressed by the schema resource. | ||
|
|
||
| The most noticeable change is the addition of the `hashing-algorithm` object | ||
| describing the hashing algorithm used in the register to create hashes for | ||
| items, entries and proofs. | ||
|
|
||
| *** | ||
| ### Endpoint | ||
|
|
||
| ``` | ||
| GET /summary | ||
| ``` | ||
|
|
||
| ### Response attributes | ||
|
|
||
| |Name|Type|Description| | ||
| |-|-|-| | ||
| |`copyright`| String |The copyright of the data.| | ||
| |`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.| | ||
| |`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. |
||
| |`total-entries`| Integer |The number of entries in the register.| | ||
| |`total-items`| Integer |The number of items in the register.| | ||
| |`total-records`| Integer |The number of records in the register.| | ||
|
|
||
| This RFC doesn't include anything related to signing root hashes. A future RFC | ||
| will expand this resource with it. | ||
|
|
||
| #### Hashing algorithm attributes | ||
|
|
||
| |Name|Type|Description| | ||
| |-|-|-| | ||
| |`digest-length`| Hexadecimal Integer |The length of the digest in bytes.| | ||
| |`function-type`| Hexadecimal Integer |The identifier of the hash function.| | ||
| |`name`| String |The common name of the algorithm.| | ||
|
|
||
| See also: [Multihash table function type | ||
| identifiers](https://github.com/multiformats/multihash/blob/master/hashtable.csv). | ||
|
|
||
| *** | ||
|
|
||
| *** | ||
| **EXAMPLE:** | ||
|
|
||
|
|
||
| ```http | ||
| GET /summary HTTP/1.1 | ||
| Accept: application/json | ||
| ``` | ||
|
|
||
| ```http | ||
| HTTP/1.1 200 OK | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "description": "List of multihash codes.", | ||
| "hashing-algorithm": { | ||
| "name": "sha2-256", | ||
| "function-type": "12", | ||
| "digest-length": "20" | ||
| }, | ||
| "total-entries": 118, | ||
| "total-items": 118, | ||
| "total-records": 118, | ||
| "custodian": "IPFS team", | ||
| "last-updated": "2017-09-04T00:00:00Z", | ||
| "copyright": "Copyright (c) 2014 Crown Copyright HM Government", | ||
| "licence": "Open Government Licence v3.0 (OGL)", | ||
| } | ||
| ``` | ||
|
|
||
| *** | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
would we want to include the root hash in this response?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, good call!