Skip to content

Commit 0379fe0

Browse files
j616j616
committed
WIP: Implementation of ADR0032
1 parent 5dbe33c commit 0379fe0

9 files changed

Lines changed: 227 additions & 35 deletions

‎api/TimeAddressableMediaStore.yaml‎

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ paths:
8989
$ref: '#/components/responses/trait_resource_listing_head_200'
9090
get:
9191
summary: Service Information
92-
description: Provide information about the service, including the media store in use.
92+
description: Provide information about the service.
9393
operationId: GET_service
9494
tags:
9595
- Service
@@ -121,6 +121,31 @@ paths:
121121
description: Success. The service info has been updated.
122122
"400":
123123
description: Bad request. Invalid service JSON.
124+
/service/storage_backends:
125+
head:
126+
summary: Storage Backend Information
127+
description: Return storage backends path headers
128+
operationId: HEAD_storage_backends
129+
tags:
130+
- Service
131+
responses:
132+
"200":
133+
$ref: '#/components/responses/trait_resource_listing_head_200'
134+
get:
135+
summary: Storage Backend Information
136+
description: Provide information about the storage backends available on this service instance. These are populated on deployment of the service instance.
137+
operationId: GET_storage_backends
138+
tags:
139+
- Service
140+
responses:
141+
"200":
142+
description: ""
143+
content:
144+
application/json:
145+
schema:
146+
$ref: schemas/storage-backends-list.json
147+
example:
148+
$ref: examples/storage-backends-get-200.json
124149
/service/webhooks:
125150
head:
126151
summary: List Webhook URLs
@@ -1522,6 +1547,14 @@ paths:
15221547
schema:
15231548
default: false
15241549
type: boolean
1550+
- name: verbose_storage
1551+
in: query
1552+
description: |
1553+
Include storage metadata in `get_urls`.
1554+
When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
1555+
schema:
1556+
default: false
1557+
type: boolean
15251558
- name: accept_get_urls
15261559
in: query
15271560
description: |
@@ -1624,6 +1657,14 @@ paths:
16241657
schema:
16251658
default: false
16261659
type: boolean
1660+
- name: verbose_storage
1661+
in: query
1662+
description: |
1663+
Include storage metadata in `get_urls`.
1664+
When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
1665+
schema:
1666+
default: false
1667+
type: boolean
16271668
- name: accept_get_urls
16281669
in: query
16291670
description: |
@@ -1748,10 +1789,10 @@ paths:
17481789
$ref: examples/flow-segment-post.json
17491790
schema:
17501791
oneOf:
1751-
- $ref: schemas/flow-segment.json
1792+
- $ref: schemas/flow-segment-post.json
17521793
- type: array
17531794
items:
1754-
$ref: schemas/flow-segment.json
1795+
$ref: schemas/flow-segment-post.json
17551796
required: true
17561797
responses:
17571798
"200":

‎api/examples/service-get-200.json‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@
44
"type": "urn:x-tams:service.example",
55
"api_version": "1.0",
66
"service_version": "tams.1.10.0-da88b8b",
7-
"media_store": {
8-
"type": "http_object_store"
9-
},
107
"event_stream_mechanisms": [
118
{
129
"name": "webhooks",

‎api/examples/storage-backends-get-200.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[
2+
{
3+
"id": "60af2ab4-e8a5-4c65-a09b-d35983680315",
4+
"label": "example-store-name",
5+
"store_type": "http_object_store",
6+
"provider": "example-cloud-provider",
7+
"region": "eu-west-1",
8+
"availability_zone": "a",
9+
"store_product": "example-storage-product",
10+
"default_storage": true
11+
},
12+
{
13+
"id": "323367fd-21bb-4f2e-ad38-faf048c4ccfc",
14+
"label": "example-alternative-store-name",
15+
"store_type": "http_object_store",
16+
"provider": "example-cloud-provider",
17+
"region": "eu-west-2",
18+
"availability_zone": "a",
19+
"store_product": "example-storage-product"
20+
}
21+
]

‎api/schemas/flow-segment-post.json‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
{
2+
"type": "object",
3+
"description": "Provides the location and metadata of the media files corresponding to timerange segments of a Flow.",
4+
"title": "Flow Segment",
5+
"required": [
6+
"object_id",
7+
"timerange"
8+
],
9+
"properties": {
10+
"object_id" : {
11+
"description": "The object store identifier for the media object.",
12+
"type": "string"
13+
},
14+
"ts_offset": {
15+
"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",
16+
"$ref": "timestamp.json"
17+
},
18+
"timerange": {
19+
"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.",
20+
"$ref": "timerange.json"
21+
},
22+
"last_duration": {
23+
"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",
24+
"$ref": "timestamp.json"
25+
},
26+
"sample_offset": {
27+
"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.",
28+
"type": "integer"
29+
},
30+
"sample_count": {
31+
"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",
32+
"type": "integer"
33+
},
34+
"get_urls": {
35+
"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.",
36+
"type": "array",
37+
"items": {
38+
"type": "object",
39+
"required": [
40+
"url"
41+
],
42+
"properties": {
43+
"url": {
44+
"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",
45+
"type": "string"
46+
},
47+
"label": {
48+
"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.",
49+
"type": "string"
50+
}
51+
}
52+
}
53+
},
54+
"key_frame_count": {
55+
"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",
56+
"type": "integer"
57+
}
58+
}
59+
}

‎api/schemas/flow-segment.json‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,24 +32,40 @@
3232
"type": "integer"
3333
},
3434
"get_urls": {
35-
"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.",
35+
"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.",
3636
"type": "array",
3737
"items": {
3838
"type": "object",
39-
"required": [
40-
"url"
41-
],
42-
"properties": {
43-
"label": {
44-
"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.",
45-
"type": "string"
39+
"unevaluatedProperties": false,
40+
"allOf": [
41+
{
42+
"$ref": "storage-backend.json"
4643
},
47-
"url": {
48-
"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",
49-
"type": "string"
44+
{
45+
"type": "object",
46+
"required": [
47+
"url"
48+
],
49+
"properties": {
50+
"url": {
51+
"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",
52+
"type": "string"
53+
},
54+
"presigned": {
55+
"description": "If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed.",
56+
"type": "boolean"
57+
},
58+
"label": {
59+
"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.",
60+
"type": "string"
61+
},
62+
"controlled": {
63+
"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`.",
64+
"type": "boolean"
65+
}
66+
}
5067
}
51-
},
52-
"additionalProperties": false
68+
]
5369
}
5470
},
5571
"key_frame_count": {

‎api/schemas/flow-storage-post.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@
66
"limit": {
77
"description": "Limit the number of storage segments in each response page. Implementations may specify their own default and maximum for the limit",
88
"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.",
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}$"
914
}
1015
}
1116
}

‎api/schemas/service.json‎

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@
44
"title": "Service",
55
"required": [
66
"type",
7-
"api_version",
8-
"media_store"
7+
"api_version"
98
],
109
"properties": {
1110
"name": {
@@ -29,20 +28,6 @@
2928
"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.",
3029
"type": "string"
3130
},
32-
"media_store": {
33-
"type": "object",
34-
"description": "Provide information about the media store for this service",
35-
"required": [
36-
"type"
37-
],
38-
"properties": {
39-
"type": {
40-
"description": "The type of the media store. This determines the endpoints for reading and writing media",
41-
"type": "string",
42-
"enum": ["http_object_store"]
43-
}
44-
}
45-
},
4631
"event_stream_mechanisms": {
4732
"type": "array",
4833
"description": "List the types of event stream that this implementation supports",

‎api/schemas/storage-backend.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"type": "object",
3+
"description": "Provides technical, and logic metadata about a storage backend",
4+
"title": "Storage Backend",
5+
"properties": {
6+
"id": {
7+
"description": "Storage backend identifier",
8+
"type": "string",
9+
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
10+
},
11+
"label": {
12+
"description": "Freeform string label for a storage backend. Will be be included alongside URLs referencing the storage backend in segment `get_urls`.",
13+
"type": "string"
14+
},
15+
"store_type": {
16+
"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`.",
17+
"type": "string",
18+
"enum": [
19+
"http_object_store"
20+
]
21+
},
22+
"provider": {
23+
"description": "The cloud (or other) provider of the storage",
24+
"type": "string"
25+
},
26+
"region": {
27+
"description": "The region in the cloud this storage backend resides",
28+
"type": "string"
29+
},
30+
"availability_zone": {
31+
"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.",
32+
"type": "string"
33+
},
34+
"store_product": {
35+
"description": "The storage product name.",
36+
"type": "string"
37+
}
38+
}
39+
}

‎api/schemas/storage-backends-list.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"type": "array",
3+
"description": "Information about the storage backends available on this service instance.",
4+
"items": {
5+
"allOf": [
6+
{
7+
"$ref": "storage-backend.json"
8+
},
9+
{
10+
"required": [
11+
"store_type",
12+
"provider",
13+
"store_product",
14+
"id"
15+
]
16+
},
17+
{
18+
"type": "object",
19+
"properties": {
20+
"default_storage": {
21+
"description": "If set to `true`, this is the default storage backend. The default storage backend will be used if the client does not specify a storage backend id when requesting the allocation of storage. If this parameter is not set, assume `false`.",
22+
"type": "boolean"
23+
}
24+
}
25+
}
26+
]
27+
},
28+
"additionalProperties": false
29+
}

0 commit comments

Comments
 (0)