Menu

Lumen help

HTTP delivery

 

HTTP delivery version 2.0

Comparison of versions 1.0 and 2.0

Terminology

  • Environment service image—a copy of a stored service image that has been promoted to the staging or production environments.
  • Property—a Lumen construct consisting of aliases filled by a specified origin. The construct is referred to by the primary alias. Usage associated with all aliases for a given property are collected and made available via the Media portal usage reporting pages or via the Media portal usage API.
  • Reporting ID—a new element introduced in HTTP delivery version 2.0. and will emerge as a more flexible way to group usage. Until the Media portal and usage API capabilities have adapted, Reporting ID Name must be set to the primary alias of the V2 representation of a property.
  • Service—synonymous with SCID and subscriber.
  • Service component ID (SCID)—a service container with the primary purpose of rolling up usage and billing.
  • Service image—a structured object used to convey caching behaviors within the CDN network. This term is often used interchangeably with “service” and “configuration”.
  • Stored service image—a configuration that is stored but not active unless promoted to an environment.
  • Subscriber—a caching service container that holds 1 or more service images. There is a 1:1 relationship between subscriber and SCID.

Simplified URI

One JSON body per service image and few API calls

Creating or updating a configuration in version 1.0 involves several granular API calls to enact caching configuration settings even though they are all for the same subscriber/service. In version 2.0, all settings for a single SCID can be made in a single API call because all configuration settings for the subscriber are represented in a single JSON body.

Stored and environment configuarions

With version 1.0, each SCID contained a single configuration. Changes to this configuration were applied to the CDN network within 15 minutes. With version 2.0, there are several improvements to note:

 

  • multiple stored configurations can be maintained for a single SCID. These are configurations that are not active in the CDN network until they are promoted. Only one configuration may be in an environment at any point in time. Among other benefits, these configurations can be worked on by multiple users until it is time to promote.

  • a staging environment is available for conducting low level testing such as sending curl commands, prior to promoting to production. When promoting a configuration, you will need to specify staging or production. Once acknowledged, most configurations are completed and distributed to the appropriate notes within a minute as opposed to 15 minutes in version 1.0.
 

When promoting a configuration with many properties, the response wait time can take several minutes. Once the response is received, it will be propagated to the edge within one or two minutes.

More configuration features

Version 2.0 supports more configuration options, such as IP/CIDR groups, accept-encoding overrides, and dynamic content transformation.

Versioning and rollbacks

Stored configurations are versioned, and any version can be promoted to an environment making it easy to revert to a previous version. When saving or promoting, a comment can be provided to aid when reviewing collaborative input from multiple users. Each environment has a version number that represents a count of promotions.

Global definitions and match rules

Except for cache control header override (CCHO) and query string handling (QSH), features are defined once and referred to within match rules reducing the overhead of managing duplicate configuration settings across multiple properties.

ID uniqueness

Within a given instances of a configuration (exp. MyConfig version 1), all element classes, such as a geo region, IDs must be unique. However, origin IDs must be unique at the SCID/subscriber level. Therefore, when promoting a new configuration that contains an origin ID that overlaps with a previously deployed origin ID for a completely different configuration, it will fail. To ensure uniqueness at the SCID/subscriber level, we recommend using a convention, such as appending EPOCH time when generating the ID.

Properties and reporting ID

In order to offer more flexibility in the near future, version 2.0 represents caching properties differently.

Request

Example: https://ws.lumen.com/serviceConfiguration/v1.0/[Access Group ID]/[SCID]

Body

{
"originserver":{
"host":" test.origin.com",
"port": "8001",
"protocol": "http"
},
"aliases":[
"test1.caching.cdn.lumen.net",
"test2.caching.cdn.lumen.net"
]
}

In version 2.0, all configuration settings can be sent in a single call. The following section describes the configuration elements that equate to creating a property. In this case an origin definition, alias definition are correlated with a reporting ID and origin ID. The primary alias is entered as the reporting ID name.

API sample V2 Create Property

Each property must have at least one match rule to match group 0 with a defined traffic type in order to be valid.

HTTP delivery version 1.0 (deprecated)

The presentation of this API is broken into different categories corresponding to the major service configuration components.

Note: HTTP delivery version 1.0 is now deprecated. It will continue to function for the remainder of 2020 or until your caching service image is converted to a format that is no longer supported by version 1.0.

Category Function Scope
Alias Retrieve, add, and remove aliases for a property. Property
Configuration groups Retrieve, add, update, and remove configuration groups for access control, cache control, and content manipulation rules associated with a resource group filter. Service or property
Geo definition Retrieve, create, update, and delete a geo definition for geo-blocking. Service or property
Origin Retrieve and update the origin server section of a property. Property
Propagation of configuration changes The service configuration services for HTTP delivery potentially affect the operation of hundreds or thousands of CDN devices globally. To efficiently manage configuration across this global network, there is a multi-tier architecture for managing network configuration where changes are queued and propagate in batch. As a result, you may experience some delay before configuration changes take effect. In particular:

  • New properties provisioned to the network may take up to 15 minutes until they are visible through the API and are available for additional service configuration.

  • Configuration changes may be confirmed immediately through the API. However, it may take up to 15 minutes to propagate to the edge servers and effect network behavior.
Properties API services for properties provide the means to create, retrieve, deactivate and reactivate properties. The create and get operations include only the basic attribution of a property, limited to origin and alias information. Service or property
Property origin aliases Retrieve, add, deactivate/reactivate a property. Service or property
Resource groups Retrieve, add, update, and remove resource groups (typically path based URI filters). Service or property
Token Retrieve, add, update, and remove token definitions for token authentication. Service or property