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 volume | 1 (fixed) | No, only matching / |
| Multi-CDN premium | 1 (fixed) | No, only matching / |
| Single-CDN | no limit | Yes, regex matching supported |
| Private-CDN | no limit | Yes, regex matching supported |
| Shield-CDN | no limit | Yes, 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 service | origin type | direct interface | interface with shield |
|---|---|---|---|
| Multi-CDN volume | simple | Y | Y |
| advanced | N | Y | |
| object storage | N | Y | |
| origin group | N | Y | |
| Multi-CDN premium | simple | Y | Y |
| advanced | N | Y | |
| object storage | N | Y | |
| origin group | N | Y | |
| Single-CDN | simple | Y | Y |
| advanced | Y | Y | |
| object storage | Y | Y | |
| origin group | Y | Y | |
| Private-CDN | simple | Y | Y |
| advanced | Y | Y | |
| object storage | Y | Y | |
| origin group | Y | Y | |
| Shield-CDN | simple | Y | - |
| advanced | Y | - | |
| object storage | Y | - | |
| origin group | Y | - |
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 service | single file | wildcard |
|---|---|---|
| Multi-CDN Volume | Y | Y |
| Multi-CDN Premium | Y | Y |
| Single-CDN | Y | N |
| Private-CDN | Y | N |
| Shield-CDN | Y | N |
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