Professional Documents
Culture Documents
CONTRIBUTORS
This document has been created by the Streaming Video Technology Alliance. It is offered to
the Alliance Membership solely as a basis for agreement and is not a binding proposal on the
companies listed as resources above. The Alliance reserves the rights to at any time add,
amend or withdraw statements contained herein. Nothing in this document is in any way
binding to the Alliance or any of its members. The user’s attention is called to the possibility
that implementation of the Alliance agreement contained herein may require the use of
inventions covered by the patent rights held by third parties. By publication of this Alliance
document, the Alliance makes no representation or warranty whatsoever, whether expressed
or implied, that implementation of the specification will not infringe any third party rights, nor
does the Alliance make any representation or warranty whatsoever, whether expressed or
implied, with respect to any claim that has been or may be asserted by any third party, the
validity of any patent rights related to any such claim, or the extent to which a license to use
any such rights may or may not be available or the terms hereof.
This document and translation of it may be copied and furnished to others, and derivative
works that comment on or otherwise explain it or assist in its implementation may be
prepared, copied, published and distributed, in whole or in part, without restriction other than
the following, (1) the above copyright notice and this paragraph must be included on all such
copies and derivative works, and (2) this document itself may not be modified in any way,
such as by removing the copyright notice or references to the Alliance, except as needed for
the purpose of developing Alliance Specifications.
By downloading, copying, or using this document in any manner, the user consents to the
terms and conditions of this notice. Unless the terms and conditions of this notice are
breached by the user, the limited permissions granted above are perpetual and will not be
revoked by the Alliance or its successors or assigns.
This document and the information contained herein is provided on an “AS IS” bases and THE
ALLIANCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE OR FITNESS FOR A PARTICULAR PURPOSE.
This document describes the Application Programming Interface (API) methods and
data model related to the Footprint and Capabilities Interface. The API has been entirely
designed by the SVTA Open Caching group whereas the data model is based on the IETF
Content Delivery Network Interconnection (CDNi) work. and on extensions specified by
the SVTA Open Caching group.
● Ratified document
1. CONTRIBUTORS 2
2. ABSTRACT 4
2.1. VERSIONING 5
3. OBJECTIVES AND SCOPE 7
3.1. Scope 7
4. INTRODUCTION 8
5. ACRONYMS AND DEFINITIONS 9
6. FOOTPRINT AND CAPABILITIES API 10
6.1. Overview 10
6.2. The Footprint & Capabilities Advertisement Interface (FCI) API 11
6.2.1. GET /OC/FCI/advertisement 11
6.2.2. POST /OC/FCI/subscription 11
6.2.3. GET | DELETE /OC/FCI/subscription/{subscriptionId} 13
7. FOOTPRINT AND CAPABILITIES DATA MODEL 15
7.1. Basic Data Model (CDNi compliant) 15
7.1.1. Structural Generic Object 15
7.1.2. Metadata Objects 16
7.2. FCI Data Model Extension 20
7.2.1. Configuration Interface 20
7.2.2. Capacity Insights Interface 20
8. SPECIFICATIONS AND STANDARD REFERENCES 21
9. TABLES AND FIGURES 22
9.1. Tables 22
9.2. Figures 22
9.3. Code 22
10. ABOUT THE STREAMING VIDEO TECHNOLOGY ALLIANCE 24
► Provide all the information software developers need to begin implementing and
3.1. Scope
The Streaming Video Technology Alliance Open Caching API (SVTA-OC-API) defines the
set of services required by the SVTA open caching ecosystem (see “Open Caching API
Implementation Guidelines”), including the Footprint and Capabilities API described in
this document.
Figure 1: SVTA Open Caching API implementation guide and related specifications
In the figure above, green indicates that the document exists, orange indicates the
document is under construction, and gray indicates a future, planned document.
The SVTA-OC-API is exposed by the telecom operator (the Internet Service Provider),
perceived as the downstream Content Delivery Network (dCDN), according to the IETF
CDNi terminology. The API is operated by either the content provider (CP) or a CDN
operator acting for the content provider and perceived as the upstream CDN (uCDN).
More generally, the API can be exposed by any CDN service operator and be used by any
upstream content provider that wishes to control that CDN.
▶ https://github.com/streaming-video-alliance/OC-API
Abbreviation Description
6.1. Overview
The Footprint and Capabilities interface is based on the IETF CDNi work, and more
precisely on RFC8008. It is discussed in the Open Cache Request Routing Service
Provisioning Interface Specification. This current document defines the API and related
data model based on OpenAPI formalism and relies on the following companion GIthub
repository.
▶ https://github.com/streaming-video-alliance/OC-API
This section describes the API methods and related data model. For more insights and
explanations, the reader must refer to the related documentation.
A simple API in pull-mode, according to the Open Cache Request Routing Service
Provisioning Interface Specification.
The advertisement file is unique and contains the complete footprint and capabilities
information structure that the dCDN/ISP wants to expose.
The OpenAPI definition of the FCI API is displayed below. The “FCI_capabilities” object
referenced in the response is described in section 6.1.1.
get:
tags:
- OC_FCI
summary: Get the FCI advertisements according to SVTA and CDNi (RFC8008/RFC8804).
operationId: oc_fci_get_advertisement
description: 'This operation is used to pull the FCI advertisement related to the requester.'
responses:
'200':
description: 'FCI advertisement'
content:
application/cdni:
schema:
$ref: './SVTA_OC_CDNI_SVTA_openapi.yaml#/components/schemas/FCI_capabilities'
'400':
description: 'Bad request'
'403':
description: 'Forbidden'
'404':
description: 'No FCI advertisement'
This API is used by the CP/uCDN to subscribe for a notification service (PUSH) that
triggers the dCDN/ISP to call the target URI back whenever the FCI dataset is modified
(i.e. any capabilities modified, added, removed for any existing, modified, new footprint
areas). If successful, the subscription ID (URI) of the subscription resource is returned in
the “Location” header of the response. It can then be read or deleted.
These methods are used to read and delete, respectively, a notification subscription
previously created with the POST /OC/FCI/subscription method.
/OC/FCI/subscription/{subscriptionId}:
get:
tags:
- OC_FCI
summary: get the FCI notification subscription
operationId: oc_fci_get_notificationSubscription
description: ''
parameters:
- name: subscriptionId
in: path
required: true
description: 'Identifier of the subscription resource. This parameter is returned when creating
the subscription.'
schema:
type: string
responses:
200:
description: 'FCI notification subscription.'
content:
application/cdni:
schema:
type: object
required:
- notificationTarget
properties:
notificationTarget:
type: string
notificationType:
type: string
enum: [fci]
400:
description: 'Bad request'
403:
description: 'Forbidden'
404:
description: 'Not found'
delete:
tags:
- OC_FCI
summary: 'delete the notification subscription'
operationId: OC_fci_delete_notificationSubscription
parameters:
- name: subscriptionId
in: path
required: true
description: 'Identifier of the subscription resource. This parameter is returned when creating
the subscription.'
schema:
type: string
responses:
200:
description: 'Notification subscription deleted'
content: {}
400:
description: Command is invalid
content: {}
403:
description: Forbidden
content: {}
The basic data model conforms with IETF CDNi in the sense that it gathers the same
objects, as defined in RFC8008 and RFC8804. However, objects described in this section
may differ from the original ones. The modifications made by SVTA may be included in
the IETF CDNi model extension.
The FCI model defines one structural object and multiple metadata objects with named
capabilities. The structural object is used to transport metadata objects in a generic and
opaque manner.
7.1.1.1. FCI_capabilities
The following script corresponds to the YAML definition extraction corresponding to the
“FCI_capabilities” object, as stored in the dedicated SVTA github repository.
FCI_capabilities:
type: object
description: 'The list of capabilities supported by the dCDN.'
properties:
capabilities:
type: array
items:
$ref: './SVTA_OC_CDNI_openapi.yaml#/components/schemas/FCI_genericbase'
FCI_capabilitytype:
type: string
enum: [FCI.Metadata, FCI.AuthTypes, FCI.ProcessingStages, FCI.SourceMetadataExtended,
FCI.RequestRouting, FCI.PrivateFeatures, FCI.OcnSelection]
FCI_genericbase:
type: object
description: 'Adding properties to the FCI_genericbase object.'
required:
7.1.2.Metadata Objects
7.1.2.1. FCI.DeliveryProtocol
This data model is discussed in the Open Cache Request Routing Service Provisioning
Interface Specification.
Note that the supported protocol list corresponds to the original CDNi definition (RFC
8006), extended with the additional values “http/2" and "http/3”.
The supported delivery protocols advertised by the dCDN should be among the list of
configurable delivery protocols. The property MI_protocol is defined in Configuration
Interface Part 3.
FCI.DeliveryProtocol:
type: object
7.1.2.2.FCI.AcquisitionProtocol
This data model is discussed in the Open Cache Request Routing Service Provisioning
Interface Specification.
The supported acquisition protocols advertised by the dCDN should be among the list of
configurable acquisition protocols. The property MI_protocol is defined in Configuration
Interface Part 3.
Note that the supported protocol list corresponds to the original CDNi definition (RFC
8006), extended with the additional values “http/2" and "http/3”.
FCI.AcquisitionProtocol:
type: object
description: 'The Acquisition Protocol capability object is used to indicate support for one or more
of the protocols listed in the "CDNI Metadata Protocol Types" registry (defined in [RFC8006]).'
required:
- acquisition-protocols
properties:
acquisition-protocols:
type: array
items:
$ref: '#/components/schemas/MI_protocol'
MI_protocol:
type: string
enum: [http/1.1, https/1.1, http/2, http/3]
7.1.2.3.FCI.RedirectionMode
The following modes are discussed in the Open Cache Request Routing Functional
Specification:
The DNS-R and HTTP-R modes must support the CDNi Request routing interface.
FCI.RedirectionMode:
type: object
description: 'List of supported CDNI redirection modes.'
required:
- redirection-modes
properties:
redirection-modes:
type: array
items:
$ref: '#/components/schemas/FCI_redirectionmode'
FCI_redirectionmode:
type: string
enum: [DNS-I, DNS-R, HTTP-I, HTTP-R]
7.1.2.4.FCI.Metadata
FCI.Metadata:
type: object
description: 'The CDNi Metadata capability object is used to indicate support for CDNi
GenericMetadata types [RFC8006].'
required:
- metadata
properties:
metadata:
description: 'List of supported CDNi GenericMetadata types. List of strings corresponding to
entries from the “CDNi payloadTypes" registry [RFC7736] that correspond to CDNi GenericMetadata objects.
An empty list MUST be interpreted as "no GenericMetadata types are supported", i.e., "only structural
metadata and simple types are supported"; otherwise, the list must be interpreted as containing "the only
GenericMetadata types that are supported" (in addition to structural metadata and simple types)
[RFC8006].'
type: array
items:
$ref: '#/components/schemas/MI_payloadtype'
MI_payloadtype:
type: string
enum: [MI.SourceMetadata, MI.Source, MI.LocationACL, MI.LocationRule, MI.Footprint,
MI.TimeWindowACL, MI.TimeWindowRule, MI.TimeWindow, MI.ProtocolACL, MI.ProtocolRule,
MI.DeliveryAuthorization, MI.Cache, MI.Auth, MI.Grouping, MI.FallbackTarget, MI.HeaderAuth, MI.AWSv4Auth,
MI.UriSigning, MI.AllowCompress, MI.CachePolicy, MI.ComputedCacheKey,MI.ComputedCacheKey,
MI.CrossoriginPolicy, MI.NegativeCachePolicy, MI.CacheBypassPolicy, MI.OcnSelection,
MI.PrivateFeatureList, MI, .ProcessingStages, MI.StageRules, MI.ExpressionMatch, MI.StageMetadata,
MI.RequestTransform, MI.ResponseTransform, MI.SyntheticResponse, MI.HeaderTransform, MI.HTTPHeader,
7.1.2.5.FCI.RedirectTarget
FCI.RedirectTarget:
type: object
description: 'FCI extension per RFC8804'
properties:
redirecting-hosts:
description: 'One or more uCDN hosts to which this redirect target is attached. A redirecting
host SHOULD be a host that was published in a HostMatch object by the uCDN as defined in Section 4.1.2 of
[RFC8006].'
type: array
items:
$ref: '#/components/schemas/MI_endpoint'
dns-target:
description: 'The DnsTarget object gives the target address for the DNS response to delegate
from the uCDN to the dCDN.'
$ref: '#/components/schemas/FCI_dnstarget'
http-target:
description: 'Target URI for an HTTP redirect.'
$ref: '#/components/schemas/FCI_httptarget'
FCI_httptarget:
type: object
description: 'FCI extension per RFC8004: the HttpTarget object gives the necessary information to
construct the target Location URI for HTTP redirection.'
required:
- host
properties:
host:
description: 'Hostname or IP address and an optional port, i.e., the host and port of the
authority component of the URI as described in Section 3.2 of [RFC3986].'
allOf:
- $ref: '#/components/schemas/MI_endpoint'
scheme:
description: 'A URI scheme to be used in the redirect response location construction. When
present, the uCDN MUST use the provided scheme for HTTP redirection to the dCDN. If this property is
absent or empty, the uCDN request router MUST use the same scheme as was used in the original request
before redirection.'
type: string
enum: [http, https]
path-prefix:
description: 'A path prefix for the HTTP redirect Location header. The original path is appended
after this prefix.'
type: string
include-redirecting-host:
description: 'A flag indicating whether or not to include the redirecting host as the first path
segment after the path-prefix. If set to true and a "path-prefix" is used, the uCDN redirecting host MUST
be added as a separate path segment after the path-prefix and before the original URL path. If set to
true and there is no path-prefix, the uCDN redirecting host MUST be prepended as the first path segment in
the redirect URL.'
type: boolean
default: false
FCI_dnstarget:
type: object
description: 'FCI extension per RFC8004: the DnsTarget object gives the target address for the DNS
response to delegate from the uCDN to the dCDN.'
required:
Some of the data model extensions are required for consistency with Configuration
Interface Part 3 V1.1. – Publishing layer APIConfiguration Interface Part 3 while others are
associated with new features, like the Capacity Insights interface.
These object definitions are detailed in the Configuration Interface Part 3 V1.1 – Publishing
layer API document. The following objects must be supported.
● FCI.AuthTypes
● FCI.ProcessingStages
● FCI.SourceMetadataExtended
● FCI.RequestRouting
● FCI.PrivateFeatures
● FCI.OcnSelection
This part of the specification relies on the Capacity Insight interface document. It defines
the SVTA open caching extension to the basic list of objects (described in Basic data
model). The following objects must be supported
● FCI.CapacityLimits
● FCI.Telemetry
9.1. Tables
9.2. Figures
9.3. Code
Comprised of members from across the video ecosystem, the Streaming Video
Technology Alliance is a global association that works to solve critical streaming video
challenges in an effort to improve end-user experience and adoption. The organization
focuses on three main activities: first is to educate the industry on challenges,
technologies, and trends through informative, publicly available resources such as
whitepapers, articles, and e-books; second is to foster collaboration among different
video ecosystem players through working groups, quarterly meetings, and conferences;
third is to define solutions for streaming video challenges by producing specifications,
best practices, and other technical documentation. For more information, please visit
https://www.svta.org.