Content Delivery

CDN or Content Delivery Network is a system of servers deployed in multiple data centers across the world. When someone pulls a file from CDN, that file is transferred to a client device via a server closest to the location of that client, which is way faster than using a route to some remote machine. Also, your file is cached on multiple servers. Hence you always get a better uptime.

On our paid plans, you can connect Uploadcare CDN to your domain or subdomain, Let’s Encrypt SSL certificate included. This is required for secure delivery

On enterprise-level plans you have an option of using any CDN you prefer on top of our infrastructure.

CDN operations

To access the Uploadcare CDN, you make requests to ucarecdn.com via HTTP or HTTPS. A valid CDN URL to request a file from Uploadcare CDN looks like this:

https://ucarecdn.com/:uuid/

CDN operations are applied to files by including URL directives in their respective CDN URLs:

https://ucarecdn.com/:uuid/-/:operation/:params/:filename

Where:

  • :uuid stands for the unique file identifier, UUID, assigned on upload.
  • /-/ is the mandatory delimiter for our parser to tell operations from one another and other path components.
  • :operation/:params/ stands for a CDN operation URL directive and related parameters.
  • :filename is an optional filename you can add after the trailing / in a CDN URL.

Pipe operations to experience the full CDN potential:

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

Filenames

Your original filenames can be accessed via our REST API. You make a request and receive a JSON response holding many file params including original_filename. However, you can decide to use any other filename; just put it after the trailing slash in your CDN URL, see :filename in the example:

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

:filename should be constructed as filename.ext and comply with the section 3.3 of RFC3986. Long story short, the symbols you use in a filename must conform to the pchar definition:

pchar = unreserved / pct-encoded / sub-delims / ":" / "@"

You can find the list of RFC3986 reserved characters here. Since we do not allow using /path/filename.ext, you can still use gen-delims without percent-encoding them, but such URLs can be unsafe to use with other services.

Here are some examples:

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. You can use those to organize content in your Uploadcare project. The advised use case for groups is using them in single content upload or delivery transactions.

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

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

:group_uuid is similar to file UUIDs with the only difference of having ~N at the end, where N stands for a number of files in a group. The maximum group file limit is 1000. We set the limit to ensure your app would optimally perform and interact with our API. Navigating through a URL holding group UUID will result in getting a list of individual UUIDs of files in that group.

Technically, our file uploader creates a file group on multi-upload using Uploadcare APIs. Learn more about creating and managing groups.

Accessing single files in a group

When working with groups, you can request a single file by using its zero-based index,

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

Note, there is no /-/ separator after a group UUID: the /nth/ URL directive does not belong to Image Transformations. Each group UUID includes a number of files in this group so you could iterate through them.

Files in a group still have support for Image Transformations,

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

You can also make groups from processed files. Such files are added together with the respective sequences of operations. So, if you request a file from a group, it is invoked with all the stored operations. Adding more controls to such files will combine them with the existing ones.

Get group as archive

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

Current operation limits are:

  • A total size of uncompressed files in a group should not exceed 2 GB.
  • Any URL directives related to processing operations are discarded within a group are discarded: only original file versions are added to the output archive.

The workflow of getting an archived file group is straight-forward:

/: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 filename: you can either specify a name for your archive or omit the parameter; more about filenames here.

Gallery from in-group files

A gallery is a way to render a group of images to 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 our Image Transformations except that we do not support image size, dimensions, and ratio manipulations here.

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

One of great use cases with gallery is embedding a collection of images right 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/