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:///#!/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:///#!/Authentication/tokeninfo

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

https:///#!/Authentication/revokeToken

Endpoint to revoke an already obtained and still active token. 

https:///#!/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:///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:///#!/Certificates/getAllCertificates

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

https:///#!/Certificates/createCertificate

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

https:///#!/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:///#!/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-‘. 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:///#!/Customer/getCustomersForLoggedInUser

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

https:///#!/Customer/createSubCustomer

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

https:///#!/Customer/deleteCustomerItsUsersAndDGroups

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

https:///#!/Customer/getCustomer

Endpoint to get customer details for a give customer Id. 

https:///#!/Customer/updateCustomer

Endpoint to update customer details for a give customer Id. 

https:///#!/Customer/disableCustomer

Endpoint for resellers to disable a sub-customer. 

https:///#!/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:///#!/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:///#!/User/getSelf

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

https:///#!/User/updateSelf

Endpoint to update details of currently logged-in user. 

https:///#!/User/getRightsSelf

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

https:///#!/User/getUsers

Endpoint to list all users for a given customer. 

https:///#!/User/deleteUser

Endpoint to delete a specific user. 

https:///#!/User/getUser

Endpoint to get details of specific user. 

https:///#!/User/updateUser

Endpoint to update a specific user.

https:///#!/User/createResellerSubUser

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

https:///#!/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:///#!/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-‘ which will used through various responses and inputs across the platform. Policies are always identified with the format ‘po-‘ and is used through various responses and inputs as well. 

Compatibility matrix:

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:///#!/Distributions/deletePrivateCdn

Endpoint to delete a Private CDN distribution.

https:///#!/Distributions/getAllPrivateCdn

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

https:///#!/Distributions/updatePrivateCdn

Endpoint to update a Private CDN distribution.

https:///#!/Distributions/getAllPrivateCdn_0

Endpoint to get a specific Private CDN distribution. 

https:///#!/Distributions/createPrivateCdn

Endpoint to create a new Private CDN distribution. 

https:///#!/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:///#!/Policies/deletePrivateCdn

Endpoint to delete a Private CDN policy for a distribution. 

https:///#!/Policies/getAllPrivateCdn

Endpoint to get all policies for a Private CDN distribution. 

https:///#!/Policies/updatePrivateCdn

Endpoint to update a policy for a distribution. 

https:///#!/Policies/getAllPrivateCdn_0

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

https:///#!/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:///#!/Distributions/deleteShieldCdn

Endpoint to delete a Shield CDN distribution.

https:///#!/Distributions/getAllShieldCdn

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

https:///#!/Distributions/updateShieldCdn

Endpoint to update a Shield CDN distribution.

https:///#!/Distributions/getAllShieldCdn_0

Endpoint to get a specific Shield CDN distribution. 

https:///#!/Distributions/createShieldCdn

Endpoint to create a new Shield CDN distribution. 

https:///#!/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:///#!/Policies/deleteShieldCdn

Endpoint to delete a shield CDN policy for a distribution. 

https:///#!/Policies/getAllShieldCdn

Endpoint to get all policies for a Shield CDN distribution. 

https:///#!/Policies/updateShieldCdn

Endpoint to update a policy for a Shield CDN distribution. 

https:///#!/Policies/getAllShieldCdn_0

Endpoint to create new Shield CDN distribution policy. 

https:///#!/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:///#!/Distributions/deleteSingleCdn

Endpoint to delete a Single CDN distribution.

https:///#!/Distributions/getAllSingleCdn

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

https:///#!/Distributions/updateSingleCdn

Endpoint to update a Single CDN distribution.

https:///#!/Distributions/getAllSingleCdn_0

Endpoint to get a specific Single CDN distribution. 

https:///#!/Distributions/createSingleCdn

Endpoint to create a new Single CDN distribution. 

https:///#!/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:///#!/Policies/getAllSingleCdn

Endpoint to delete a Single CDN policy for a distribution. 

https:///#!/Policies/updateSingleCdn

Endpoint to update a policy for a Single CDN distribution. 

https:///#!/Policies/getAllSingleCdn_0

Endpoint to create new Single CDN distribution policy. 

https:///#!/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:///#!/Distributions/deleteMultiCdnPremium

Endpoint to delete a Multi-CDN Premium distribution.

https:///#!/Distributions/getAllMultiCdnPremium

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

https:///#!/Distributions/updateMultiCdnPremium

Endpoint to update a Multi CDN premium distribution.

https:///#!/Distributions/getAllMultiCdnPremium_0

Endpoint to get a specific Multi CDN premium distribution. 

https:///#!/Distributions/createMultiCdnPremium

Endpoint to create a new Multi CDN premium distribution. 

https:///#!/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:///#!/Policies/getAllMultiCdnPremium

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

https:///#!/Policies/updateMultiCdnPremium

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

https:///#!/Policies/getAllMultiCdnPremium_0

Endpoint to create new Multi CDN premium distribution policy. 

https:///#!/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:///#!/Distributions/deleteMultiCdnVolume

Endpoint to delete a Multi-CDN Premium distribution.

https:///#!/Distributions/getAllMultiCdnVolume

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

https:///#!/Distributions/updateMultiCdnVolume

Endpoint to update a Multi CDN volume distribution.

https:///#!/Distributions/getAllMultiCdnVolume_0

Endpoint to get a specific Multi CDN volume distribution. 

https:///#!/Distributions/createMultiCdnVolume

Endpoint to create a new Multi CDN volume distribution. 

https:///#!/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:///#!/Policies/getAllMultiCdnVolume

Endpoint to delete a Multi CDN volume for a distribution. 

https:///#!/Policies/updateMultiCdnVolume

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

https:///#!/Policies/getAllMultiCdnVolume_0

Endpoint to create new Multi CDN volume policy. 

https:///#!/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-‘ or ‘og-‘ 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. 

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:///website_images/image.png. 

https:///#!/Origins/deleteAdvancedOrigin

Endpoint to delete the Advanced origin. 

https:///#!/Origins/getByIdAdvancedOrigin

Endpoint to get a specific Advanced origin.

https:///#!/Origins/updateAdvancedOrigin

Endpoint to update a specific Advanced origin. 

https:///#!/Origins/getAllAdvancedOrigins

Endpoint to get all Advanced origin for a given customer. 

https:///#!/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:///#!/Origins/deleteSimpleOrigin

Endpoint to delete a specific simple origin.

https:///#!/Origins/getByIdSimpleOrigin

Endpoint to get a specific simple origin.

https:///#!/Origins/updateSimpledOrigin

Endpoint to update a specific simple origin. 

https:///#!/Origins/getAllSimpleOrigins

Endpoint to get all simple origins for a given customer. 

https:///#!/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:///#!/Origins/deleteObjectStorageOrigin

Endpoint to delete an Object storage origin. 

https:///#!/Origins/getByIdObjectStorageOrigin

Endpoint to get a specific Object storage origin. 

https:///#!/Origins/updateObjectStorageOrigin

Endpoint to update a specific Object storage origin. 

https:///#!/Origins/getAllObjectStorageOrigins

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

https:///#!/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:///#!/Origins/deleteGroupsOrigin

Endpoint to delete an Origin group. 

https:///#!/Origins/getByIdGroupsOrigin

Endpoint to get a specific Origin group. 

https:///#!/Origins/updateGroupsOrigin

Endpoint to update a specific Origin group. 

https:///#!/Origins/getAllGroupsOrigins

Endpoint to get all Origin groups for a given customer. 

https:///#!/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:

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:///#!/Invalidations/getInvalidations

Endpoint to get invalidation requests for a given customer. 

https:///#!/Invalidations/doInvalidate

Endpoint to create a new invalidation request. 

https:///#!/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:///#!/Statistics/query

https:///#!/Statistics/query_0