API v3 Migration guide

With the release of the new REST API version 3, several changes related to your CDN Resource management were introduced. This guide summarizes the changes so you can migrate your applications without any obstacles.

1. Authentication

The previous version of the API used your client panel username & API password set in the query or body parameters of the API request. In API v3 all you need for authenticating with our API is the new token, which can be generated in your client panel. You can also generate multiple tokens for use with different app integrations etc.

Generate your API token here, and find out how to make your first request in the new API introduction here.

2. Identifiers

For most of the Rest API operations we’re using UUIDv4 identifiers,which have replaced the previously used integer identifiers; however, there are a few exceptions – most notably the CDN Resource ID. In API v2 we had used a short integer id, this identifier has now been deprecated and is now only available for legacy purposes. Our latest API now uses the CDN Resource ID, which is available in the Client Panel as well as the CDN Resource list via API.

You may be familiar with this identifier from your CDN Resource URL e.g.1234567890.rsc.cdn77.org - however please note the URL is not the identifier, only the number used in it.

3. Origins

You may have noticed some of these changes in our Client Panel already, from now on all CDN Resources have migrated to this setup.

Our previous version of API allowed you to set up a new CDN Resource programmatically with a single request to /cdn-resource/create with your origin url and other settings. Our new API v3 allows you to create a new CDN Resource associated with a pre-existing origin URL or, alternatively, a new origin must be created for the new Resource.

4. Reports/Statistics

The new API v3 includes a Statistics section, which replaces the Reports section from API v2. The new statistics allow you to access more detailed reports and make better use of the data regarding your CDN Resources.

The statistics API now allows you to use data aggregation for a specific request scope. For example, if you want to retrieve data for the scope of the last 24 hours, you can request the data with 1-h (1 hour) aggregation. The API response will include 24 timestamps, allowing you to built statistics, charts, etc., instead of the total report for the requested scope.

You can also make use of multiple endpoints, one used for totals across all your inputs, another that can respond with the data foreach CDN Resource used in your request, or even detailed Datacenter/Continent statistics.

5. Jobs

The new API includes a Jobs section, this section replaces the API v2 Data Management & Data Queue sections and allows you to enqueue your cache purge & cache prefetch requests, list your enqueued jobs or details of the job.

The API works more or less the same, however there’s a few differences:

Paths

This parameter is used with both purge & prefetch requests, it replaces the url parameter used with APIv2 and takes an array of paths on your origin/storage that you want to purge or prefetch.

Prefetch

For prefetch you may notice a new parameter that can be used in your request - upstream_host - this option is required for prefetch requests with CDN Resources that have the forward host header option enabled in your CDN Resource settings. The upstream host can only be one of your CNAMEs or CDN URL.

6. Errors

If you send an incorrectly formatted API request or there’s any issue with the API, you should receive a JSON response including the specified validation error or an error message that may point you toward the solution of the occurrence.

The format of the error responses is following:

{
  "errors": [
    "Error message", 
    "...possibly other errors"
  ],
  "fields": [
    "field": [
      "Error message about field being invalid",
      "...other errors regarding the field"
    ]
  ]
}
        

The "fields" may only be present when a field is invalid - e.g. for 422 status code responses. Other errors may only include the "errors" part of the response.

Note the API will only respond with a 2xx status code when the request has been successfully processed.