Link Search Menu Expand Document

CDN

Getting started

You must configure the CDN before you can use it. Please make sure you have read this brief Getting Started page before you proceed.

How the CDN feature works in Skyfish

The CDN feature works using a ‘magic’ folder. We will call this magic folder the CDN folder from hereon.

For an in-depth explanation of how files are stored in folders in Skyfish, read our guide to Folders in Skyfish.

To make a file accessible via the CDN, copy or move the file into the CDN folder.

Once the file is added to the CDN folder, Skyfish will automatically generate a unique URL that points to the file. This URL is called the file’s CDN Link. A file’s CDN Link makes it accessible from outside Skyfish, via the CDN.

To stop making a file accessible via the CDN, simply remove the file from the CDN folder. Skyfish will automatically delete the file’s CDN Link.

Using the Skyfish CDN from the API

You must first find the ID of the CDN folder.

A Skyfish user can belong to more than one company, so remember to specify the correct company-id for the CDN. (If you are in doubt about what your Company ID is, reach out to us on api@colourbox.com.)

Execute:

GET https://api.colourbox.com/cdn/<company-id>/company/aliases

You will receive output that looks like this:

{
  "count": 1,
  "limit": 1,
  "aliases": [
    {
      "folder_id": 1337,
      "alias": "cdn-tutorial",
      "folder_name": "CDN"
    }
  ]
}

In this example, the ID of the CDN folder is 1337.

The alias is part of all URLs generated as CDN Links. In this example, the alias is cdn-tutorial, so any CDN Link URLs generated will be in the format: https://cdn.skyfish.com/cdn-tutorial/<id>

The format of a CDN Link URL is:

https://cdn.skyfish.com/<alias>/<id>.<extension>

The id is automatically generated by Skyfish.

The .extension part of the URL is optional. Our API will always include it when you request a CDN Link URL, but all CDN Links will still work with it omitted.

For example: assume 12345 is a valid ID for a jpeg file with the extension .jpg. The following CDN Link URLs will both work:

  • https://cdn.skyfish.com/cdn-tutorial/12345.jpg
  • https://cdn.skyfish.com/cdn-tutorial/12345

To generate a CDN Link URL for a file, move or copy the file to the CDN folder.

For example: assume you want to generate a link for the media with a unique_media_id of 42424242. Execute:

POST https://api.colourbox.com/media/42424242/folder/1337

Once the file is in the folder, Skyfish will queue it for CDN Link creation. Usually, the CDN Link will be ready within 20 seconds.

NOTE: You will need full read- and write-access to the CDN folder, and to at least one of the other folders in Skyfish where the file was originally stored.

All search endpoints support asking for cdn_urls as a return value. To retrieve the CDN Link for a specific file, specify the unique_media_id as a search parameter, and pass cdn_urls as the value for the variable return_values:

GET api.colourbox.com/search?unique_media_id=42424242&return_values=cdn_urls

The response will look like this:

{
  "response": {
    "media": [
      {
        "cdn_urls": [
          "https://cdn.skyfish.com/cdn-tutorial/<id>.<extension>"
        ]
      }
    ],
    "hits": 1
  },
  "media_count": 1,
  "media_offset": 0
}

NOTE: Because CDN Link creation uses our internal queuing system, there may be a delay. If cdn_urls is empty even though the file was placed in the CDN folder, wait a few seconds, and try again.

You can change which file an active CDN Link points to without changing the CDN Link.

This can be very useful. For example, assume you store the header image for your homepage on Skyfish. Your homepage uses a CDN Link for the image’s URL in the source code. When you want to update the page’s header, simply update which image file the CDN Link URL points to. There is no need to edit the homepage to add a new URL for a new image.

Let’s continue this example in detail, to illustrate this feature.

You have a CDN Link that points to a file with the unique media ID 101. To update the CDN Link to point to a new file with the unique media ID 202, execute:

NOTE: This is a POST call

POST api.colourbox.com/cdn/<company-id>/folder/<cdn-folder-id>/replace/101/with/202

Note that, as mentioned above, to do this you must know your Company ID, and the unique ID of your CDN folder.

To delete a CDN Link for a file, remove the file from the folder.

For example, to remove the media with a unique_media_id of value 42424242:

DELETE api.colourbox.com/media/42424242/folder/<cdn-folder-id>

NOTE: This is a DELETE call.

Note also that, as above, to do this you must know the unique ID of your CDN folder.

You can manipulate how a media file’s CDN Link presents the media by appending query parameters to it.

We support the following parameters:

Parameter Description
width Specify the width of the image
height Specify the height of the image
grayscale Make the image grayscale
output_format The media file’s format

The aspect ratio is automatically maintained. Specify either width or height, but not both.

For output_format file formats, we support the following:

  • webp
  • jpeg

Example

https://cdn.skyfish.com/cdn-tutorial/12345.jpeg?width=800&output_format=webp

This will return the file 12345.jpeg resized to be 800 pixels wide and in the webp file format.