CDN File API

File API is about accessing single files on Uploadcare CDN. All of the file URLs begin with the assigned UUIDs. That is the basic case, and such links will simply return the original file,

https://ucarecdn.com/:uuid/

CDN filenames

Your original filenames can still 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 Media Processing operations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/resize/550x/image@1x.jpg

// using a sub-delim allowed in pchar together with Media Processing operations
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

Media Processing

You can also process any file on the CDN using our Media Processing. This requires appending processing operations to your file URL using /-/ as a separator. Each operation has its name and arguments, which are separated by forward slashes, /. Here, take a look at the example,

https://ucarecdn.com/:uuid/-/resize/200x/-/rotate/90/

In the example, we just invoked the two image processing operations: resize with the argument 200x and rotate with the argument 90.

As mentioned, you can complete a URL holding processing operations with a filename of your preference.

Image processing operations are part of Uploadcare Media Processing.

Further, your files can be arranged in groups, which behavior is regulated by our Group API.

Authenticated URLs

You can control who and when have access to files uploaded to your account. The functionality is provided by the Uploadcare feature called Authenticated URLs or Signed URLs. When enabled, a user will require a token to access your content.

Token authentication also ensures a URL can only be accessed within a defined time span. Once a token expires, the content will no longer be accessible. To re-access the content, a new URL should be generated.

The Authenticated URLs feature may be useful when:

  • Your users upload personal, medical or other sensitive data.
  • You want your content to be rendered by authorized users only.
  • You want users to access your content only within a specified time frame.

Authenticated URLs work together with custom domains; you should set up a custom CNAME before using the feature. The format of an authenticated URL depends on a CDN provider your custom domain is connected to. We are currently working with Akamai and KeyCDN.

This is how secure URLs look like:

Akamai,

https://cdn.yourdomain.com/{uuid}/?token=exp={timestamp}~data=my_signature_data~hmac={token}

KeyCDN,

https://cdn.yourdomain.com/{uuid}/?token={token}&expire={timestamp}

Where:

  • cdn.yourdomain.com is your custom CNAME.
  • {uuid} is a unique file identifier or UUID.
  • {token} is a generated token used to access your content using a signed URL.
  • {timestamp} is an expiry date provided with the access token.

Note, {timestamp} must be defined as the Unix time when a provided token is set to expire.

Access tokens are generated on your backend. There is plenty of ready-made solutions for popular languages:

  • For Akamai (C, C#, Erlang, Go, Java, Perl, PHP, Python, Ruby)
  • For KeyCDN (PHP, Python, Ruby, NodeJS, Java)

Drop us a line in case you want to enable the Authenticated URLs feature for your account.

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.