Implementation of ADR0032

j616 · j616 · commit bac8cce4fe65 · 2025-06-09T17:44:55.000+01:00
sem-ver: api-break
diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml
@@ -89,7 +89,7 @@ paths:
           $ref: '#/components/responses/trait_resource_listing_head_200'
     get:
       summary: Service Information
-      description: Provide information about the service, including the media store in use.
+      description: Provide information about the service.
       operationId: GET_service
       tags:
         - Service
@@ -121,6 +121,31 @@ paths:
           description: Success. The service info has been updated.
         "400":
           description: Bad request. Invalid service JSON.
+  /service/storage_backends:
+    head:
+      summary: Storage Backend Information
+      description: Return storage backends path headers
+      operationId: HEAD_storage_backends
+      tags:
+        - Service
+      responses:
+        "200":
+          $ref: '#/components/responses/trait_resource_listing_head_200'
+    get:
+      summary: Storage Backend Information
+      description: Provide information about the storage backends available on this service instance. These are populated on deployment of the service instance.
+      operationId: GET_storage_backends
+      tags:
+        - Service
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              schema:
+                $ref: schemas/storage-backends-list.json
+              example:
+                $ref: examples/storage-backends-get-200.json
   /service/webhooks:
     head:
       summary: List Webhook URLs
@@ -1522,18 +1547,47 @@ paths:
           schema:
             default: false
             type: boolean
+        - name: verbose_storage
+          in: query
+          description: |
+            Include storage metadata in `get_urls`.
+            When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
+          schema:
+            default: false
+            type: boolean
         - name: accept_get_urls
           in: query
           description: |
             A comma separated list of labels of flow segment `get_urls` to include in the response.
-            Omitting `accept_get_urls` will result in all `get_urls` returned.
+            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 cannot be filtered for; they will only be returned if `accept_get_urls` is omitted.
+            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.
             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.
           schema:
             type: string
             pattern: ^([^,]+(,[^,]+)*)?$
+        - name: accept_storage_ids
+          in: query
+          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`.
+            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.
+            A full list of available `storage_id`s may be found at the `service/storage_backends` endpoint.
+          schema:
+            type: string
+            pattern: ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(,[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})*$
+        - name: presigned
+          in: query
+          description: |
+            If set to `true`, only presigned URLs (i.e. those whos `presigned` property is `true`) will be returned in `get_urls`.
+            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls`.
+            If omitted, both presigned and non-presigned URLs will be returned.
+            If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to
+            generate a large number of pre-signed URLs.
+          schema:
+            type: boolean
         - $ref: '#/components/parameters/trait_resource_paged_key'
         - $ref: '#/components/parameters/trait_paged_limit'
       responses:
@@ -1624,18 +1678,47 @@ paths:
           schema:
             default: false
             type: boolean
+        - name: verbose_storage
+          in: query
+          description: |
+            Include storage metadata in `get_urls`.
+            When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
+          schema:
+            default: false
+            type: boolean
         - name: accept_get_urls
           in: query
           description: |
             A comma separated list of labels of flow segment `get_urls` to include in the response.
-            Omitting `accept_get_urls` will result in all `get_urls` returned.
+            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 cannot be filtered for; they will only be returned if `accept_get_urls` is omitted.
+            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.
             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.
           schema:
             type: string
             pattern: ^([^,]+(,[^,]+)*)?$
+        - name: accept_storage_ids
+          in: query
+          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`.
+            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.
+            A full list of available `storage_id`s may be found at the `service/storage_backends` endpoint.
+          schema:
+            type: string
+            pattern: ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(,[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})*$
+        - name: presigned
+          in: query
+          description: |
+            If set to `true`, only presigned URLs (i.e. those whos `presigned` property is `true`) will be returned in `get_urls`.
+            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls`.
+            If omitted, both presigned and non-presigned URLs will be returned.
+            If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to
+            generate a large number of pre-signed URLs.
+          schema:
+            type: boolean
         - $ref: '#/components/parameters/trait_resource_paged_key'
         - $ref: '#/components/parameters/trait_paged_limit'
       responses:
@@ -1748,10 +1831,10 @@ paths:
               $ref: examples/flow-segment-post.json
             schema:
               oneOf:
-              - $ref: schemas/flow-segment.json
+              - $ref: schemas/flow-segment-post.json
               - type: array
                 items:
-                  $ref: schemas/flow-segment.json
+                  $ref: schemas/flow-segment-post.json
         required: true
       responses:
         "200":
diff --git a/api/examples/service-get-200.json b/api/examples/service-get-200.json
@@ -4,9 +4,6 @@
   "type": "urn:x-tams:service.example",
   "api_version": "1.0",
   "service_version": "tams.1.10.0-da88b8b",
-  "media_store": {
-    "type": "http_object_store"
-  },
   "event_stream_mechanisms": [
     {
       "name": "webhooks",
diff --git a/api/examples/storage-backends-get-200.json b/api/examples/storage-backends-get-200.json
@@ -0,0 +1,21 @@
+[
+  {
+    "id": "60af2ab4-e8a5-4c65-a09b-d35983680315",
+    "label": "example-store-name",
+    "store_type": "http_object_store",
+    "provider": "example-cloud-provider",
+    "region": "eu-west-1",
+    "availability_zone": "a",
+    "store_product": "example-storage-product",
+    "default_storage": true
+  },
+  {
+    "id": "323367fd-21bb-4f2e-ad38-faf048c4ccfc",
+    "label": "example-alternative-store-name",
+    "store_type": "http_object_store",
+    "provider": "example-cloud-provider",
+    "region": "eu-west-2",
+    "availability_zone": "a",
+    "store_product": "example-storage-product"
+  }
+]
diff --git a/api/schemas/flow-segment-post.json b/api/schemas/flow-segment-post.json
@@ -0,0 +1,59 @@
+{
+  "type": "object",
+  "description": "Provides the location and metadata of the media files corresponding to timerange segments of a Flow.",
+  "title": "Flow Segment",
+  "required": [
+    "object_id",
+    "timerange"
+  ],
+  "properties": {
+    "object_id" : {
+      "description": "The object store identifier for the media object.",
+      "type": "string"
+    },
+    "ts_offset": {
+      "description": "The timestamp offset between the sample timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative",
+      "$ref": "timestamp.json"
+    },
+    "timerange": {
+      "description": "The timerange for the samples contained in the segment. The timerange start is always inclusive. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](../schemas/timerange#top) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline.",
+      "$ref": "timerange.json"
+    },
+    "last_duration": {
+      "description": "The difference between the exclusive end of the `timerange` and the last sample timestamp. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative",
+      "$ref": "timestamp.json"
+    },
+    "sample_offset": {
+      "description": "The start of the segment represented as a count of samples from the start of the object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set.",
+      "type": "integer"
+    },
+    "sample_count": {
+      "description": "The count of samples in the segment (which may be fewer than in the object). The count could be less than expected given the segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples",
+      "type": "integer"
+    },
+    "get_urls": {
+      "description": "A list of URLs to which a GET request can be made to directly retrieve the contents of the segment. This is required by the `http_object_store` media store type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however servers may sort the list such that the preferred URL is first. `get_urls` should only be used to add uncontrolled URLs. URLs for the provided object_id controlled by the service instance will be populated automatically by the service instance.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "url"
+        ],
+        "properties": {
+          "url": {
+            "description": "A URL to which a GET request can be made to directly retrieve the contents of the segment. Clients should include credentials if the provide URL is on the same origin as the API endpoint",
+            "type": "string"
+          },
+          "label": {
+            "description": "Label identifying this URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "key_frame_count": {
+      "description": "The number of key frames in the segment. This should be set greater than zero when the segment contains key frames that serve as a stream access point",
+      "type": "integer"
+    }
+  }
+}
diff --git a/api/schemas/flow-segment.json b/api/schemas/flow-segment.json
@@ -32,24 +32,40 @@
       "type": "integer"
     },
     "get_urls": {
-      "description": "A list of URLs to which a GET request can be made to directly retrieve the contents of the segment. This is required by the `http_object_store` media store type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however servers may sort the list such that the preferred URL is first.",
+      "description": "A list of URLs to which a GET request can be made to directly retrieve the contents of the segment. This is required by the `http_object_store` media store type, which is the only one currently described. Clients may choose any URL in the list and treat the content returned as identical, however servers may sort the list such that the preferred URL is first.",
       "type": "array",
       "items": {
         "type": "object",
-        "required": [
-          "url"
-        ],
-        "properties": {
-          "label": {
-            "description": "Label identifying this URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.",
-            "type": "string"
+        "unevaluatedProperties": false,
+        "allOf": [
+          {
+            "$ref": "storage-backend.json"
           },
-          "url": {
-            "description": "A URL to which a GET request can be made to directly retrieve the contents of the segment. Clients should include credentials if the provide URL is on the same origin as the API endpoint",
-            "type": "string"
+          {
+            "type": "object",
+            "required": [
+              "url"
+            ],
+            "properties": {
+              "url": {
+                "description": "A URL to which a GET request can be made to directly retrieve the contents of the segment. Clients should include credentials if the provide URL is on the same origin as the API endpoint",
+                "type": "string"
+              },
+              "presigned": {
+                "description": "If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed.",
+                "type": "boolean"
+              },
+              "label": {
+                "description": "Label identifying this URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.",
+                "type": "string"
+              },
+              "controlled": {
+                "description": "If `true`, this URL is on a storage backend controlled by this service instance. If `false`, this URL is uncontrolled and does not have it's lifecycle managed by this instance. If this parameter is unset, assume `true`.",
+                "type": "boolean"
+              }
+            }
           }
-        },
-        "additionalProperties": false
+        ]
       }
     },
     "key_frame_count": {
diff --git a/api/schemas/flow-storage-post.json b/api/schemas/flow-storage-post.json
@@ -6,6 +6,11 @@
         "limit": {
             "description": "Limit the number of storage segments in each response page. Implementations may specify their own default and maximum for the limit",
             "type": "integer"
+        },
+        "storage_id": {
+            "description": "The storage backend to allocate storage in. A storage backend identifier as advertised at the `/service` endpoint. If not set the default, as advertised at the `/service` endpoint, will be used if available. An invalid storage backend identifier will result in a 400 error.",
+            "type": "string",
+            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
         }
     }
 }
diff --git a/api/schemas/service.json b/api/schemas/service.json
@@ -4,8 +4,7 @@
   "title": "Service",
   "required": [
     "type",
-    "api_version",
-    "media_store"
+    "api_version"
   ],
   "properties": {
     "name": {
@@ -29,20 +28,6 @@
       "description": "The version of software providing this service. Note: Different implementations and software houses may use different conventions for their version identification. As such, this field is intentionally permissive and intended to be informative only. Implementations should avoid using this field to determine compatibility.",
       "type": "string"
     },
-    "media_store": {
-      "type": "object",
-      "description": "Provide information about the media store for this service",
-      "required": [
-        "type"
-      ],
-      "properties": {
-        "type": {
-          "description": "The type of the media store. This determines the endpoints for reading and writing media",
-          "type": "string",
-          "enum": ["http_object_store"]
-        }
-      }
-    },
     "event_stream_mechanisms": {
       "type": "array",
       "description": "List the types of event stream that this implementation supports",
diff --git a/api/schemas/storage-backend.json b/api/schemas/storage-backend.json
@@ -0,0 +1,39 @@
+{
+    "type": "object",
+    "description": "Provides technical, and logic metadata about a storage backend",
+    "title": "Storage Backend",
+    "properties": {
+        "id": {
+            "description": "Storage backend identifier",
+            "type": "string",
+            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+        },
+        "label": {
+            "description": "Freeform string label for a storage backend. Will be be included alongside URLs referencing the storage backend in segment `get_urls`.",
+            "type": "string"
+        },
+        "store_type": {
+            "description": "The generic store type. Used to identify the required workflow for reading and writing media. Any `store_product` should be compatible, as much is required for basic interoperability between TAMS implementations, with their associated generic `store_type`.",
+            "type": "string",
+            "enum": [
+                "http_object_store"
+            ]
+        },
+        "provider": {
+            "description": "The cloud (or other) provider of the storage",
+            "type": "string"
+        },
+        "region": {
+            "description": "The region in the cloud this storage backend resides",
+            "type": "string"
+        },
+        "availability_zone": {
+            "description": "The availability zone in the cloud region this storage backend resides. Note that many cloud providers randomize availability zone identifiers such that they are consistent within a cloud account, but not necessarily between accounts. Caution should be exercised when using this parameter.",
+            "type": "string"
+        },
+        "store_product": {
+            "description": "The storage product name.",
+            "type": "string"
+        }
+    }
+}
diff --git a/api/schemas/storage-backends-list.json b/api/schemas/storage-backends-list.json

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,11 @@`
`6`	`6`	`"limit": {`
`7`	`7`	`"description": "Limit the number of storage segments in each response page. Implementations may specify their own default and maximum for the limit",`
`8`	`8`	`"type": "integer"`
	`9`	`+ },`
	`10`	`+ "storage_id": {`
	`11`	+ "description": "The storage backend to allocate storage in. A storage backend identifier as advertised at the `/service` endpoint. If not set the default, as advertised at the `/service` endpoint, will be used if available. An invalid storage backend identifier will result in a 400 error.",
	`12`	`+ "type": "string",`
	`13`	`+ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"`
`9`	`14`	`}`
`10`	`15`	`}`
`11`	`16`	`}`