Content Delivery Network

CDN is a geographically distributed system of servers that delivers content to client devices from the servers nearby, which saves time on long-distance data exchange. In addition to faster page load, delivery networks store cached files on multiple servers and provide a better uptime in case some servers become inaccessable.

Uploadcare uses Akamai CDN and a proprietary CDN layer for better performance and reliability.

CDN operations

Access files in Uploadcare CDN at ucarecdn.com over HTTP/HTTPS liks this:

https://ucarecdn.com/:uuid/

You can add CDN operations by including directives in the CDN URL:

https://ucarecdn.com/:uuid/-/:operation/:params/:filename
  • :uuid stands for the unique file identifier, UUID, assigned on upload.
  • /-/ is a mandatory parsing delimiter to divide operations and other path components.
  • :operation/:params/ is a CDN operation directive with parameters.
  • :filename is an optional filename you can add after a trailing slash /.

You can stack two and more operations like this:

-/:operation/:params/-/:operation/:params/

Filenames

Your original filenames can be accessed via REST API. Make a request to receive a JSON response with file parameters including original_filename.

You can set an optional filename that users will see instead of the original name:

https://ucarecdn.com/:uuid/:filename

:filename should comply with file name conventions and it should be a valid part of a URL. For example, filename.ext.

Here are some examples with full CDN URLs:

Safe:

// adding a simple filename
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image.jpg

// using a char allowed in the pchar definition
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image@2x.jpg

// allowed in pchar together with Image Transformations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/resize/550x/image@1x.jpg

// using a sub-delim allowed in pchar together with Image Transformations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image_black&white@2x.jpg

// using percent-encoded gen-delims that are not allowed in pchar
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image%5Bdesaturated%5D@2x.jpg

Unsafe:

// using gen-delims that are not allowed in pchar without encoding
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image[desaturated]@2x.jpg

Group API

What a group is

Groups are file collections. Use them to organize content in your Uploadcare project. A common use case is to use them in single content upload or delivery transactions.

For instance, each time you use multi-upload with File Uploader, a new group is created. It stores UUIDs of uploaded files. You can access file collections via :group_uuid:

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/

:group_uuid is similar to a single file UUID, but it has the file number ~N at the end. A group can contain up to 1000 files.

A group URL will show a list of individual file URLs with their UUIDs, and index numbers in that group.

Technically, our File Uploader will create a group on multi-upload using Uploadcare APIs. Learn more about creating and managing groups.

Accessing single files in a group

Request a specific file in a group by adding /nth/i/, where i is a file index, starting from 0:

/:group_uuid/nth/0/
/:group_uuid/nth/1/
/:group_uuid/nth/2/

Note, there is no /-/ separator after a group UUID. It's required for transformations only.

By the way, you can apply Image Transformations to indivitual files within a group:

/:group_uuid/nth/0/-/resize/256x/

You can also group the processed files with the respective operation sequences. When you request a file by its group URL, it'll include all operations before adding to that group. Adding more operations after /-/ will apply them over the existing ones.

Get a group as an archive

Getting a group as an archive is done via the archive group processing operation.

The operation limits are:

  • A total size of uncompressed files ≤ 2 GB.
  • Processing operations will be discarded. Only original files will be archived.

Here's how to get an archived file group:

/:group_uuid/archive/:format/:filename
  • :group_uuid — UUID of a file group you want to get as an archive.
  • :format — the format of that output archive, we support zip and tar.
  • :filename (optional) — output archive filename.

Gallery from in-group files

A gallery will display a group of images on a single page. The gallery feature is powered by the Fotorama JavaScript library.

Making a gallery is also based on a group processing operation, gallery. Here’s how it works,

/:group_uuid/gallery/

You can customize the layout and behavior of images in a gallery by adding Fotorama options to their URLs. The workflow is pretty much the same as with Image Transformations except for image size, dimensions, and ratio manipulations.

/:group_uuid/gallery/-/nav/thumbs/-/fit/cover/-/autoplay/1000/

The most common use case with gallery is to embed a collection of images into your page via <iframe>,

<iframe
  src="/:group_uuid/gallery/-/nav/thumbs/-/fit/cover/-/loop/true/-/allowfullscreen/native/-/thumbwidth/100/"
  width="100%"
  height="450"
  allowfullscreen="true"
  frameborder="0">
</iframe>

Show or Download Images

-/inline/yes/
-/inline/no/

By default, CDN instructs browsers to show images and download other file types. The inline control allows you to change this behavior.

/:uuid/-/preview/-/inline/no/
/:uuid/-/inline/yes/

File Information

Get file info as JSON

-/json/

Returns file-related information, such as image dimensions or geotagging data in the JSON format.

/:uuid/-/json/
/:uuid/-/preview/-/json/

In the second option, json response will contain the original key with the info on your original image.

Get file info as application/javascript

-/jsonp/

Same as the example above, but it returns data as the application/javascript type. Callback name should always be uploadcare_callback. It should receive the two following arguments: id and a response object. For original files, id is na equivalent to their UUIDs. For processed files, id is an equivalent to their URLs, excluding the last operation, jsonp.

/:uuid/-/jsonp/
/:uuid/-/preview/-/jsonp/

In the first case id will be c5b7dd84-c0e2-48ff-babc-d23939f2c6b4, in the second: /c5b7dd84-c0e2-48ff-babc-d23939f2c6b4/-/preview/.

Custom CNAME

Depending on your plan, you can connect Uploadcare CDN to your domain or subdomain with a Let’s Encrypt SSL certificate. Enterprise plans let you choose any CDN you prefer.