CDN API documentation


General information

The CDN API is a self-described RESTful API using OpenAPI specification. All endpoints are described with:

  • example responses
  • expected response codes with example responses 
  • data models
  • input parameters (if any) 
  • input payload (if any) 

Accessing the API directly (i.e. https://api.synedge.com / https://api.cdn.leaseweb.com / etc) will land on the SwaggerUI that uses the OpenAPI specifications to create a visual representation of the endpoints and will allow to send and receive requests within the browser as well as showing example cURL commands to reproduce the results from your CLI. The required bearer token will be automatically taken for the session if a customer logins to their account via the CDN portal and would browse to the 'API documentation' via the fly-out menu's on the top right. 

The following described endpoints reflect the SwaggerUI entry points, which will describe the actual API endpoint and the expected input / output. 

Endpoints

The endpoints described here point towards the appropriate SwaggerUI locations where the expected input and output is reflected and gives you the ability the run test requests. The test requests also produce re-usable cURL commands.

Authentication

All endpoints relating to obtaining, refreshing and revoking of authentication tokens. 

https://<CDN API>/#!/Authentication/clientToken

Endpoint that will generate a client token outside of the context of a user. In most cases the user token in the endpoint below is what is used for obtaining the required bearer token.  

https://<CDN API>/#!/Authentication/tokeninfo

Endpoint that will respond back with some basic information about the provided token. 

https://<CDN API>/#!/Authentication/revokeToken

Endpoint to revoke an already obtained and still active token. 

https://<CDN API>/#!/Authentication/authenticateLogin

Main endpoint to obtain the bearer token in order to authenticate to other endpoints to require authentication. 

The API relies on a Oauth2 spec authentication using the provided or created username/password combination. With this username/password combination a token can be generated which can be used to authenticate on all secured API endpoints by setting the correct headers.  For obtaining a token the following fields are required:

  • username (i.e. user account you login to, in the form of an email address) 
  • password 
  • correct grant type (password in most cases) 

The 2FA field is only required if 2FA is enabled for the user that is used to login with. 

If the username/password combination is correct the API will respond back with a token which will be valid for a number of seconds: 

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' -d 'username=example-user&password=example-password&grant_type=password' 'https://<CDN API>/auth/token'
{
  "access_token": "120bf05ee0991b822aa3ac4d47a045bb",
  "expires_in": 3600,
  "refresh_token": null,
  "token_type": "bearer"
}

If the refresh token functionally is desired the client_id and client_secret should also be specified and re-used in the refresh token call. For more information on Oauth2 and its specification please go through the documentation on: https://oauth.net/2/

Certificates

Certificates are managed centrally and can be re-used across different distributions or even distribution types across a single customer. The platform does not allow for any duplicate private key/certificate combinations, these will always need to be unique. Certificates cannot be shared across customers meaning that two different customers cannot upload a certificate with the same private key / certificate pair. 

When uploading a certificate there will be validation done by default. This validation checks the validity of the certificate  (i.e. is the certificate not expired) but also if the provided private key and certificate match and if the supplied bundle creates a fully trusted chain. 


https://<CDN API>/#!/Certificates/getAllCertificates

Endpoint that will list all certificates that are coupled with the provided customer.

https://<CDN API>/#!/Certificates/createCertificate

Endpoint to upload a new certificate, private key and chain combination. 

https://<CDN API>/#!/Certificates/deleteCertificate

Endpoint to delete an existing certificate. The platform will check if the certificate is not coupled with a distribution. To delete a certificate no distributions can be configured to use this certificate.

https://<CDN API>/#!/Certificates/getByIdCertificate

Endpoint to obtain information of the certificate and its current validity. 

Customer

Within the CDN platform the customer account is where most entities (i.e. configurations, invalidations, etc) are coupled with. All customers are identified with the form of 'cu-<hash>'. This is an unique identifier that will be used in most endpoints in order to work with the correct data set. Generally a customer is the main entity of a CDN account. 

In the event of a reseller customer account, which is an account that is used to manage its sub-customers, various endpoints are used. 


https://<CDN API>/#!/Customer/getCustomersForLoggedInUser

Endpoint for resellers that will list the customers for the logged in reseller customer. 

https://<CDN API>/#!/Customer/createSubCustomer

Endpoint for resellers to create a new sub-customer account.

https://<CDN API>/#!/Customer/deleteCustomerItsUsersAndDGroups

Endpoint for resellers to delete a sub-customer, its users and other entities. 

https://<CDN API>/#!/Customer/getCustomer

Endpoint to get customer details for a give customer Id. 

https://<CDN API>/#!/Customer/updateCustomer

Endpoint to update customer details for a give customer Id. 

https://<CDN API>/#!/Customer/disableCustomer

Endpoint for resellers to disable a sub-customer. 

https://<CDN API>/#!/Customer/disableCustomer

Endpoint for resellers to enable a sub-customer. 

User

Any customer account can have multiple user accounts. An user account is used to login to the platform using a username (which is always an email address)  + password combination and any customer will require at least one user (with admin role). Different users can have different roles. Currently the following roles can be configured for a user:

  • admin: this is the role that has access to all parts of the platform for a given customer
  • read-only: this role is only able to read data from the platform for a given customer
  • invalidate-only: this role is only allowed to do invalidation requests and check their status

Roles are configured to have certain rights. These rights are what is used to authorise certain actions on the platform. 


https://<CDN API>/#!/User/forgotPassword

Endpoint used to go to forget-your-password flow in the event a user can no longer login. Forgot your password will only work for users that we have an account for and will not indicate if an user account actually exists. 

https://<CDN API>/#!/User/getSelf

Endpoint to get information for the currently logged-in user. 

https://<CDN API>/#!/User/updateSelf

Endpoint to update details of currently logged-in user. 

https://<CDN API>/#!/User/getRightsSelf

Endpoint to list the rights that are applicable to the role of the currently logged-in user. 

https://<CDN API>/#!/User/getUsers

Endpoint to list all users for a given customer. 

https://<CDN API>/#!/User/deleteUser

Endpoint to delete a specific user. 

https://<CDN API>/#!/User/getUser

Endpoint to get details of specific user. 

https://<CDN API>/#!/User/updateUser

Endpoint to update a specific user.

https://<CDN API>/#!/User/createResellerSubUser

Endpoint for resellers to create a user for their reseller account. 

https://<CDN API>/#!/User/enable2FA

Endpoint to enable 2FA for currently logged-in user. The response will give back the secret that needs to be used to authenticate when 2FA is enabled. It is no longer possible to only login with just your username and password.  


Roles

Roles are attached to users and roles have rights to define what a role is able to do. These roles and rights are defined by CDN support. 

https://<CDN API>/#!/Roles/getRoles

Endpoint to get the roles and the rights of those roles. 

Distributions and Policies

The main component for defining a CDN configuration is called a distribution. The distribution by itself has some configurable items like domains and TLS but will not function without at least one policy. The policy is the place where the majority of the CDN settings are configured, including which origin to use. The distribution is always identified by using the format 'di-<hash>' which will used through various responses and inputs across the platform. Policies are always identified with the format 'po-<hash>' and is used through various responses and inputs as well. 

Compatibility matrix:

service

no. policies

supports regex
Multi-CDN volume1 (fixed)No, only matching /
Multi-CDN premium1 (fixed)No, only matching /
Single-CDNno limitYes, regex matching supported
Private-CDNno limitYes, regex matching supported
Shield-CDNno limitYes, regex matching supported


Private-CDN

The Private-CDN service is a dedicated set of CDN locations and nodes that are deployed in specific locations or inside local networks. This is a bespoke service and can managed via the API and/or UI. The Private-CDN can be coupled together with the (public) Single, Shield and Multi-CDN services to achieve infinite scale, availability and/or geographic reach. 


https://<CDN API>/#!/Distributions/deletePrivateCdn

Endpoint to delete a Private CDN distribution.

https://<CDN API>/#!/Distributions/getAllPrivateCdn

Endpoint to get all Private CDN distributions for a given customer. 

https://<CDN API>/#!/Distributions/updatePrivateCdn

Endpoint to update a Private CDN distribution.

https://<CDN API>/#!/Distributions/getAllPrivateCdn_0

Endpoint to get a specific Private CDN distribution. 

https://<CDN API>/#!/Distributions/createPrivateCdn

Endpoint to create a new Private CDN distribution. 

https://<CDN API>/#!/Distributions/getPrivateCdnStatus

Endpoint get the deployment status for a Private CDN distribution. In case of issues deploying the configuration this endpoint will give back more information on where and why it failed. 

https://<CDN API>/#!/Policies/deletePrivateCdn

Endpoint to delete a Private CDN policy for a distribution. 

https://<CDN API>/#!/Policies/getAllPrivateCdn

Endpoint to get all policies for a Private CDN distribution. 

https://<CDN API>/#!/Policies/updatePrivateCdn

Endpoint to update a policy for a distribution. 

https://<CDN API>/#!/Policies/getAllPrivateCdn_0

Endpoint to get a specific policy for a Private CDN distribution. 

https://<CDN API>/#!/Policies/createPrivateCdn

Endpoint to create new Private CDN distribution policy. 


Shield-CDN

The Shield-CDN service is intended to act as an intermediate caching layer between the (public) CDN's (Single, Multi or Private) and the origin(s). It will greatly mitigate any origin traffic to achieve a better cache-hit ratio and origin offload/reduce egress costs. It can also add more advanced configuration logic to add more flexibility to a typical Multi-CDN deployment. 

https://<CDN API>/#!/Distributions/deleteShieldCdn

Endpoint to delete a Shield CDN distribution.

https://<CDN API>/#!/Distributions/getAllShieldCdn

Endpoint to get all shield CDN distributions for a given customer. 

https://<CDN API>/#!/Distributions/updateShieldCdn

Endpoint to update a Shield CDN distribution.

https://<CDN API>/#!/Distributions/getAllShieldCdn_0

Endpoint to get a specific Shield CDN distribution. 

https://<CDN API>/#!/Distributions/createShieldCdn

Endpoint to create a new Shield CDN distribution. 

https://<CDN API>/#!/Distributions/getShieldCdnStatus

Endpoint get the deployment status for a Shield CDN distribution. In case of issues deploying the configuration this endpoint will give back more information on where and why it failed. 

https://<CDN API>/#!/Policies/deleteShieldCdn

Endpoint to delete a shield CDN policy for a distribution. 

https://<CDN API>/#!/Policies/getAllShieldCdn

Endpoint to get all policies for a Shield CDN distribution. 

https://<CDN API>/#!/Policies/updateShieldCdn

Endpoint to update a policy for a Shield CDN distribution. 

https://<CDN API>/#!/Policies/getAllShieldCdn_0

Endpoint to create new Shield CDN distribution policy. 

https://<CDN API>/#!/Policies/createShieldCdn

Endpoint to create new Shield CDN distribution policy.


Single-CDN

The Single-CDN service is hosted in set of high-capacity locations based upon the Leaseweb network in North-America, Europe and Asia. 

https://<CDN API>/#!/Distributions/deleteSingleCdn

Endpoint to delete a Single CDN distribution.

https://<CDN API>/#!/Distributions/getAllSingleCdn

Endpoint to get all Single CDN distributions for a given customer. 

https://<CDN API>/#!/Distributions/updateSingleCdn

Endpoint to update a Single CDN distribution.

https://<CDN API>/#!/Distributions/getAllSingleCdn_0

Endpoint to get a specific Single CDN distribution. 

https://<CDN API>/#!/Distributions/createSingleCdn

Endpoint to create a new Single CDN distribution. 

https://<CDN API>/#!/Distributions/getSingleCdnStatus

Endpoint get the deployment status for a Single CDN distribution. In case of issues deploying the configuration this endpoint will give back more information on where and why it failed. 

https://<CDN API>/#!/Policies/getAllSingleCdn

Endpoint to delete a Single CDN policy for a distribution. 

https://<CDN API>/#!/Policies/updateSingleCdn

Endpoint to update a policy for a Single CDN distribution. 

https://<CDN API>/#!/Policies/getAllSingleCdn_0

Endpoint to create new Single CDN distribution policy. 

https://<CDN API>/#!/Policies/createSingleCdn

Endpoint to create new Single CDN distribution policy.


Multi-CDN premium

The Multi-CDN service is designed to simplify setting up, maintaining and monitoring a set of global CDN's aggregated into a single API and UI. The Multi-CDN has two tiers: volume and premium. Premium consists of multiple CDN's with local coverage in almost all countries and regions of the world with around hundreds of PoP's globally with 100+ of Terabits per second of capacity. 

https://<CDN API>/#!/Distributions/deleteMultiCdnPremium

Endpoint to delete a Multi-CDN Premium distribution.

https://<CDN API>/#!/Distributions/getAllMultiCdnPremium

Endpoint to get all Multi CDN premium distributions for a given customer. 

https://<CDN API>/#!/Distributions/updateMultiCdnPremium

Endpoint to update a Multi CDN premium distribution.

https://<CDN API>/#!/Distributions/getAllMultiCdnPremium_0

Endpoint to get a specific Multi CDN premium distribution. 

https://<CDN API>/#!/Distributions/createMultiCdnPremium

Endpoint to create a new Multi CDN premium distribution. 

https://<CDN API>/#!/Distributions/getMultiPremiumCdnStatus

Endpoint get the deployment status for a Multi CDN premium distribution. In case of issues deploying the configuration this endpoint will give back more information on where and why it failed. 

https://<CDN API>/#!/Policies/getAllMultiCdnPremium

Endpoint to delete a Multi CDN premium policy for a distribution. 

https://<CDN API>/#!/Policies/updateMultiCdnPremium

Endpoint to update a policy for a Multi CDN premium distribution. 

https://<CDN API>/#!/Policies/getAllMultiCdnPremium_0

Endpoint to create new Multi CDN premium distribution policy. 

https://<CDN API>/#!/Policies/createMultiCdnPremium

Endpoint to create new Multi CDN premium distribution policy.


Multi-CDN volume

The Multi-CDN service is designed to simplify setting up, maintaining and monitoring a set of global CDN's aggregated into a single API and UI. The Multi-CDN has two tiers: volume and premium. Volume consists of multiple CDN's with local coverage in most countries/states in Europe (incl. CIS/Russia), North-America, South-America, the Middle-East, Oceania and Asia with around 150 PoP's globally with dozens of Terabits per second of capacity. 

https://<CDN API>/#!/Distributions/deleteMultiCdnVolume

Endpoint to delete a Multi-CDN Premium distribution.

https://<CDN API>/#!/Distributions/getAllMultiCdnVolume

Endpoint to get all Multi CDN volume distributions for a given customer. 

https://<CDN API>/#!/Distributions/updateMultiCdnVolume

Endpoint to update a Multi CDN volume distribution.

https://<CDN API>/#!/Distributions/getAllMultiCdnVolume_0

Endpoint to get a specific Multi CDN volume distribution. 

https://<CDN API>/#!/Distributions/createMultiCdnVolume

Endpoint to create a new Multi CDN volume distribution. 

https://<CDN API>/#!/Distributions/getMultiVolumeCdnStatus

Endpoint get the deployment status for a Multi CDN volume distribution. In case of issues deploying the configuration this endpoint will give back more information on where and why it failed. 

https://<CDN API>/#!/Policies/getAllMultiCdnVolume

Endpoint to delete a Multi CDN volume for a distribution. 

https://<CDN API>/#!/Policies/updateMultiCdnVolume

Endpoint to update a policy for a Multi CDN volume distribution. 

https://<CDN API>/#!/Policies/getAllMultiCdnVolume_0

Endpoint to create new Multi CDN volume policy. 

https://<CDN API>/#!/Policies/createMultiCdnVolume

Endpoint to create new Multi CDN volume distribution policy.

Origins

Different types of origins can be setup to fetch the content from. Only origin pull options are supported at this time.

The different services have different constrains on what origin it can directly interface with. For the Multi-CDN services for example the shield can be used to mitigate this and interface with all types of origins indirectly as a translation layer. 

Origins are always referenced by its ID, which is a hash that starts with 'or-<hash>' or 'og-<hash>' in case of an origin group. 

Note: the protocol of how to interface with an origin/origin group is always defined on the policy level, not not on the origin level. Meaning that you will at all times only define the hostname or IP of the origins in the origin configuration and select either HTTP or HTTPS in the policy connected to this origin. 

CDN serviceorigin typedirect interfaceinterface with shield
Multi-CDN volumesimpleYY

advancedNY

object storageNY

origin groupNY
Multi-CDN premiumsimpleYY

advancedNY

object storageNY

origin groupNY
Single-CDNsimpleYY

advancedYY

object storageYY

origin groupYY
Private-CDNsimpleYY

advancedYY

object storageYY

origin groupYY
Shield-CDNsimpleY-

advancedY-

object storageY-

origin groupY-


Advanced origin

The advanced origin can be used in the case that the origin is using non-standard ports to access the HTTP or HTTPS content, or in the event that the content is under a sub-directory which should be omitted from the end-user CDN URL. For example: the advanced origin can be configured to use the path '/website_images' whereas the CDN URL for the end-users would be https://cdn.example.org/image.png, the actual internal (CDN to origin request) in this case would be https://<origin host>/website_images/image.png. 

https://<CDN API>/#!/Origins/deleteAdvancedOrigin

Endpoint to delete the Advanced origin. 

https://<CDN API>/#!/Origins/getByIdAdvancedOrigin

Endpoint to get a specific Advanced origin.

https://<CDN API>/#!/Origins/updateAdvancedOrigin

Endpoint to update a specific Advanced origin. 

https://<CDN API>/#!/Origins/getAllAdvancedOrigins

Endpoint to get all Advanced origin for a given customer. 

https://<CDN API>/#!/Origins/createAdvancedOrigin

Endpoint to create a new Advanced origin. 

Simple origin

The simple origin is the, as the name implies, the simplest option available. The configuration can be done by just setting the hostname or IP of the origin to pull the content from. No other configuration other than a description is available. 

https://<CDN API>/#!/Origins/deleteSimpleOrigin

Endpoint to delete a specific simple origin.

https://<CDN API>/#!/Origins/getByIdSimpleOrigin

Endpoint to get a specific simple origin.

https://<CDN API>/#!/Origins/updateSimpledOrigin

Endpoint to update a specific simple origin. 

https://<CDN API>/#!/Origins/getAllSimpleOrigins

Endpoint to get all simple origins for a given customer. 

https://<CDN API>/#!/Origins/createSimpleOrigin

Endpoint to create a new simple origin. 


Object storage origin

The object storage origin can be used to interface with various Object Storage platforms which are S3 compatible and require authentication. Currently only v2 type authentication is supported. If not authentication is required a normal simple origin can be used by using the full URL to the object storage platform and bucket. 

https://<CDN API>/#!/Origins/deleteObjectStorageOrigin

Endpoint to delete an Object storage origin. 

https://<CDN API>/#!/Origins/getByIdObjectStorageOrigin

Endpoint to get a specific Object storage origin. 

https://<CDN API>/#!/Origins/updateObjectStorageOrigin

Endpoint to update a specific Object storage origin. 

https://<CDN API>/#!/Origins/getAllObjectStorageOrigins

Endpoint to get all Object storage origins for a given customer. 

https://<CDN API>/#!/Origins/createObjectStorageOrigin

Endpoint to create a new Object storage origin. 

Origin groups

Origin groups are intended to group multiple origins together to achieve either resilience or additional scale. Only simple origins can be added to an origin group. 

https://<CDN API>/#!/Origins/deleteGroupsOrigin

Endpoint to delete an Origin group. 

https://<CDN API>/#!/Origins/getByIdGroupsOrigin

Endpoint to get a specific Origin group. 

https://<CDN API>/#!/Origins/updateGroupsOrigin

Endpoint to update a specific Origin group. 

https://<CDN API>/#!/Origins/getAllGroupsOrigins

Endpoint to get all Origin groups for a given customer. 

https://<CDN API>/#!/Origins/createGroupsOrigin

Endpoint to create a new Origin group. 


Invalidations

In order to remove content from the CDN caches there is the option to invalidate (or purge) the content by issuing an invalidation request.

Invalidation requests can be done on a single file or, depending on the service, with a wildcard invalidation request. A wildcard request will remove all the files that match under the wildcard from the cache. Depending on the used service invalidation can take from a couple of seconds to 15 minutes. 

Compatibly matrix for single file invalidations and wildcard invalidations:

CDN servicesingle filewildcard
Multi-CDN VolumeYY
Multi-CDN PremiumYY
Single-CDNYN
Private-CDNYN
Shield-CDNYN

Invalidation requests always list the URL including the domain name, the protocol set in the invalidation request will be omitted as there is no difference in the cached asset between the protocols in the used CDN's. The invalidation requests are processed and handled in an asynchronous manner and you should take into account: 

  • only one invalidation request will be handled per minute 
  • one invalidation request can have multiple lines (i.e. files / wildcards) to invalidate but only 75 are taken into account per invalidation request. This means that if you issue an invalidation request with 150 lines, this will take at least 2 minutes to be processed 
  • if invalidations are queued too long (i.e. in the event a lot of invalidation requests with large number of lines are submitted and are not processed yet due to the above limits), an invalidation request can be set to expire and thus will no longer be queued to be processed. 


https://<CDN API>/#!/Invalidations/getInvalidations

Endpoint to get invalidation requests for a given customer. 

https://<CDN API>/#!/Invalidations/doInvalidate

Endpoint to create a new invalidation request. 

https://<CDN API>/#!/Invalidations/getInvalidation

Endpoint to get information per line that was part of the same invalidation request. 

Statistics

The statistics endpoints are currently undergoing various improvements and rewrites, in oder to advise on what endpoints to use or the timing for implementing them it is best to reach out to support for now. 

https://<CDN API>/#!/Statistics/query


https://<CDN API>/#!/Statistics/query_0