The version of an image is the timestamp of uploading the image (e.g., v1366687335). It is required for building URLs of the latest uploaded version of an image in case that multiple images were uploaded sharing the same public ID (overwriting a previously uploaded image). It allows bypassing a previously cached version of the image.
Each image (public ID) has only the latest uploaded version available for delivery and transformation. The version value is included in the response of our upload API call.
Here's a sample URL with the version component:
http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg
Cloudinary's does not require the version component to be present in URLs (but you might get a previously cached version in this case). For example:
http://res.cloudinary.com/demo/image/upload/sample.jpg
However, if your public ID includes folders (elements divided by '/'), the version component is mandatory, but you can make it shorter. For example:
http://res.cloudinary.com/demo/image/upload/v1/sample_folder/sample_name.jpg
Comments
12 comments
If we have an image that has been uploaded/overwritten numerous times it will have an updated version number. If the image also includes a '/' within its public id and we retrieve the image using the shortened v1 method in the url will we be guaranteed to get the latest version?
Hi Michael,
For images within folders (or any images which their public IDs include the '/' character), due to technical reasons related to naming convention, Cloudinary's integration libraries automatically add the 'v1' parameter. However, to bypass CDN cache, and forcing delivery of the newest image, the version component must be added.
For example, if the latest image's version is '1364158979' (The
versionparameter is returned with every upload call), then a URL like the following should be used:http://res.cloudinary.com/<your\_cloud\_name>/image/upload/v1364158979/multiple/folders/sample.jpg
Here's a code example in .NET:
@Model.Cloudinary.Api.UrlImgUp.Version("1364158979").BuildImageTag("multiple/folders/sample.jpg")
Orly, you say that the version value of an image is included in the response of your upload API call. This makes sense, and I see this behavior in my app.
My question is: can this information be retrieved from the API (or, more specifically, from the Java library) apart from an upload call?
Here's my use case. I store images using a public ID derived from the ID of an account in the database. For example, a company's logo might have the public ID
company/1/logoif their internal ID is 1. The point is, I don't save any information in my database about the public ID of their logo image. So, when that image needs to change, I re-upload a new image with the same public ID. Because this change takes a while to propagate through the various layers of caching, they will continue to see the old image for a while, unless I give them the URL of the *versioned* image instead of the default URL.So, is there a way to get the URL of the versioned image without saving information from the upload request? Thanks for your help.
Hi Jeff,
While we warmly recommend to also store the 'version' value returned by every upload call in your database, you can use the Admin API to get full details of your resources, including the
versionparameter and theurlparameter (which already includes the 'version' component).For more information (in JAVA):
http://cloudinary.com/documentation/java_additional_topics#admin_api
Note that in default the Admin API is rate limited to 500 calls per hour (12,000 daily).
Can I just confirm two things:
Are they correct? Thanks!
Hi Adam,
While you're basically correct, please allow me to further explain.
Let's say you use a URL like the following to deliver your image (without the version component):
http://res.cloudinary.com/demo/image/upload/sample.jpg
If you're not planning on overriding the image, the version component is optional, hence - you can deliver the image without the version value as part of the URL (even without 'v1') and the image will be delivered as usual.
On the other hand, when you do override the image (e.g., upload a new image while setting its public ID to be the same as the already stored image), the image is updated in your Cloudinary account, but if you access the exact same URL you might be still getting the older (CDN cached) version of the image.
Therefore, the solution for this is to alter the URL so that you can still access the same public ID of your Cloudinary account, while also bypass the cached CDN versions and force the delivery of the newest image.
For this to happen you should use a unique URL which isn't cached in the CDN, e.g., a URL which was not yet accessed. If the URL with 'v1' was never accessed before, then adding 'v1' would deliver the newer version.
In order to avoid keeping track of which version value was accessed before or not, Cloudinary helps you keeping the version value unique with every re-upload of the image. The updated version value is returned with each upload (the version value is a representation of the upload's timestamp). Updating the URL to use the new version value will ensure that you have the latest version of the image.
I hope that helps.
That helps Itay!
Can I ask for one further clarification, so I can be sure I understand what's going on:
The point of using the version is to use it to "cache bust" - to make sure the URL is new and therefore cause the cache to refresh. So, naively, you could use any random version number, and assuming that the CDN had never been asked for that version number previously, it would dump its cached copy and refresh from the main Cloudinary store.
Which would be pointless of course because that would mean the CDN would always refresh (because the URL always contained a random version).
So by using the actual latest version number, you ensure a CDN cache refresh when it is needed, and then in the future, when your request that same (latest) version again, you get a cached copy (thereby taking advantage of the CDN cache).
What it does not do, is allow you to access an earlier version. Requesting an earlier version might get you that earlier version for a while, until the CDN cache is refreshed, but you can't go back through the history of the versions by passing earlier version IDs.
Is that right?
Yes David, that is correct.
Note that images are cached for one month. So after a full month has passed, all earlier versions of the image will be gone.
If having access to an earlier version of the image is something that you require, you should probably consider to not override the image in the first place and maybe use a new public ID when re-uploading.
Hello,
I'm using Android library. While I fetch the URL using the following code, I dont' get the version number and hence I don't get the latest image but the cached one. How can I get the latest image URL? I don't want to provide the version number explicitly myself but to fetch it.
Android Code
cloudinary.url().secure(true).format("jpg").generate("public-id-of-image");
Response - https://res.cloudinary.com/13568798jhk/v1429795291/ojpz1z9xfpwszka23thc.jpg
Sorry for the very late reply, we have noticed that this request was left unattended. I guess this is not relevant anymore but for future reference -
You can specify the version number by adding it as a parameter. For example,
cloudinary.url().version().secure(true).format("jpg").generate("public-id-of-image");
> However, if your public ID includes folders (elements divided by '/'), the version component is mandatory, but you can make it shorter.
Is this still true? We use folders and it seems that images in folders work even without the version segment in the URL.
While serving images is possible in folders without use of a version segment in the URL, we state that it's mandatory because if it's excluded there are side-effects related to caching and invalidation which may not be desirable.
In particular, if you use a URL structure with folders but without a version component, when you replace an image with a newer version, the old URL won't be invalidated on the CDN, and users may see the old version until the cache expires.
For more information please see 'asset versions' in the upload documentation or the section in the same document which discusses 'invalidating cached assets in the CDN'
Please sign in to leave a comment.