diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml index c5284280..1d2601cc 100644 --- a/api/TimeAddressableMediaStore.yaml +++ b/api/TimeAddressableMediaStore.yaml @@ -2003,11 +2003,10 @@ paths: A service instance MAY support Media Objects that are held in external storage in another TAMS or other media storage system. The Flow Segment may in that case require the `get_urls` property to provide the information needed by clients to access the Media Object. - Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata as such operations will likely break the idempotency of Segments. - Properties of Media Objects, such as `get_urls`, SHOULD be modified via the [`/objects`](#/operations/GET_objects) endpoints. - They SHOULD NOT be modified at this endpoint, and TAMS instences SHOULD reject such requests with a `400` error. + The list of instances of an object (and associated `get_urls` entries) can be modified via the [`/objects`](#/operations/GET_objects) endpoints, which provides a mechanism to register new instances of an object. - If a client needs to modify a Flow Segment, e.g. to correct metadata such as the `key_frame_count` or add additional URLs to `get_urls`, then the client SHOULD first delete the existing Segment and then write a new one. + Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata such as `key_frame_count`, as such operations will likely break the idempotency of Segments. + If a client needs to modify a Flow Segment, then the client SHOULD first delete the existing Segment and then write a new one. The behaviour is undefined if the Segment exists and the service may return a 400 error response. For successful creation of all Segments in the request a 201 response should be provided. @@ -2016,11 +2015,13 @@ paths: Clients are expected to decide how to break content into Media Objects, however those Objects SHOULD be large enough to avoid excessive round trip overheads in the underlying store (_e.g._ of the order of several megabytes) and where codecs with temporal re-ordering are used, Object SHOULD contain complete GOPs or decodable units. - For Media Objects that have been re-used from other Flows, the `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use: + For Media Objects that have been re-used from elsewhere, the `sample_offset` and `sample_count` MAY be used to specify part of the Media Object to use: - The `timerange` field indicates the new Segment's position in the Flow - The sample associated with the start of the `timerange` MUST be the one selected by `sample_offset` - Likewise, the sample associated with the end of the `timerange` MUST be the one selected by `sample_offset + sample_count - 1`, unless `timerange` has an exclusive end, in which case it will be `sample_offset + sample_count`. - The timerange of the Segment MUST NOT overlap any other Segment in the same Flow. + + When re-using Media Objects, requests which change object properties (e.g. `key_frame_count`) SHOULD be rejected. operationId: POST_flows-flowId-segments tags: - FlowSegments diff --git a/docs/appnotes/0018-managing-multiple-object-instances.md b/docs/appnotes/0018-managing-multiple-object-instances.md index b7a50850..e967ead5 100644 --- a/docs/appnotes/0018-managing-multiple-object-instances.md +++ b/docs/appnotes/0018-managing-multiple-object-instances.md @@ -108,12 +108,13 @@ Example POST body to `/objects/{objectId}/instances`: ### Deleting an Object Instance -Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/get_urls` with the relevant `storage_id` in the query string. +Specific instances of a Media Object can be deleted by a DELETE request to `/objects/{objectId}/instances` with the relevant `storage_id` in the query string. +However attempting to delete the last instance of a media object should be rejected: this requires deleting the referencing Flow Segments instead. Example DELETE request: ```text -http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/get_urls?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc +http://tams.example.com/objects/846023d3-612d-5014-bc47-88f6eb2d04bb/instances?storage_id=323367fd-21bb-4f2e-ad38-faf048c4ccfc ``` Once deleted, this instance will no longer be advertised in `get_urls` on the `/objects/{objectId}` endpoint or on the `/flows/{flowId}/segments` for Flow Segments which use the Media Object.