diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index 065f3d8e..725c4134 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -1785,7 +1785,7 @@ paths: A comma separated list of labels of Flow Segment `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1795,7 +1795,7 @@ paths: description: | A comma separated list of `storage_id`s of Flow Segment `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1912,7 +1912,7 @@ paths: A comma separated list of labels of Flow Segment `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -1922,7 +1922,7 @@ paths: description: | A comma separated list of `storage_id`s of Flow Segment `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Flow Segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Flow Segment `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -2194,7 +2194,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2205,7 +2205,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: @@ -2291,7 +2291,7 @@ paths: A comma separated list of labels of Media Object `get_urls` to include in the response. Omitting `accept_get_urls` will result in no filtering of `get_urls`. An empty `accept_get_urls` results in an empty or no `get_urls` in the response. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no label will only be returned if `accept_get_urls` is omitted. Without `get_urls`, the response from the service could be substantially faster if it is not required to generate a large number of pre-signed URLs for example. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. @@ -2302,7 +2302,7 @@ paths: description: | A comma separated list of `storage_id`s of Media Object `get_urls` to include in the response. Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`. - Media object `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty. + Media Object `get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty. A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint. Where multiple filter query parameters are provided, the returned `get_urls` will match all filters. schema: diff --git a/api/schemas/flow-segment-post.json b/api/schemas/flow-segment-post.json index 31a86a51..9bbdf0a6 100644 --- a/api/schemas/flow-segment-post.json +++ b/api/schemas/flow-segment-post.json @@ -55,7 +55,8 @@ "type": "object", "required": [ - "url" + "url", + "label" ], "properties": { @@ -66,7 +67,7 @@ }, "label": { - "description": "Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.", + "description": "Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. Service implementations should reject any requests containing multiple `get_urls` with the same `label`.", "type": "string" } } diff --git a/api/schemas/objects-instances-post.json b/api/schemas/objects-instances-post.json index 74cc4f46..e4b8e81c 100644 --- a/api/schemas/objects-instances-post.json +++ b/api/schemas/objects-instances-post.json @@ -22,7 +22,8 @@ "title": "Uncontrolled instance", "type": "object", "required": [ - "url" + "url", + "label" ], "properties": { "url": { @@ -30,7 +31,7 @@ "type": "string" }, "label": { - "description": "Label identifying this Media Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends. If the 'label' is not set then this instance can't be filtered for using the 'accept_get_urls' API query parameter.", + "description": "Label identifying this Media Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends.", "type": "string" } } diff --git a/docs/README.md b/docs/README.md index 8d760cfb..38706d3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,5 +74,6 @@ For more information on how we use ADRs, see [here](./adr/README.md). | [0039](./adr/0039-remove-pre-actions.md) | Proposal to remove pre-actions from storage allocation response | | [0040](./adr/0040-tag-usability-enhancements.md) | Tag Usability Enhancements | | [0041](./adr/0041-require-explicit-framerate.md) | Requiring explicit frame rates | +| [0042](./adr/0042-uncontrolled-object-instance-labels.md) | Make `label` Mandatory for Uncontrolled Object Instances | \* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication diff --git a/docs/adr/0042-uncontrolled-object-instance-labels.md b/docs/adr/0042-uncontrolled-object-instance-labels.md new file mode 100644 index 00000000..a76f3970 --- /dev/null +++ b/docs/adr/0042-uncontrolled-object-instance-labels.md @@ -0,0 +1,35 @@ +--- +status: "accepted" +--- +# Make `label` Mandatory for Uncontrolled Object Instances + +## Context and Problem Statement + +In [ADR0038](./0038-improved-storage-management.md), we added endpoints under `/objects` to facilitate the management of multiple Object Instances. +Since accepting that ADR, we have received feedback that `label` being optional for uncontrolled Object Instances makes it unclear how such Object Instances should be managed. +This ADR seeks to remedy that by making `label` mandatory when registering new uncontrolled Object Instances. + +## Considered Options + +* Option 1: Leave `label` as optional when registering uncontrolled Object Instances +* Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +## Decision Outcome + +Chosen Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +### Implementation + +Implemented by + +## Pros and Cons of the Options + +### Option 1: Leave `label` as optional when registering uncontrolled Object Instances + +* Neutral, because this avoids a breaking change to a lesser used part of the API +* Bad, because mechanisms for managing uncontrolled Object Instances without labels are undefined, because there is no natural key by which to identify a particular Object Instance - for example `DELETE /objects/{objectId}/instances` requires a label (or storage ID) + +### Option 2: Make `label` mandatory when registering uncontrolled Object Instances + +* Good, because mechanisms for managing all Object Instances will be defined +* Neutral, because this is a breaking change to a lesser used part of the API that will be released alongside the existing changes to Object management mechanisms