Accounts created before Nov. 1st, 2021
Accounts created before November 1, 2021 have to include /v7/ in the path, like shown below.
//token.cloudimg.io/v7/original_image_url?operations&filters
Accounts created on or after November 1, 2021 do not require /v7/ and documentation have been updated accordingly.
To verify the type of configuration on your Cloudimage account, log in to your Cloudimage admin panel and look at the syntax provided on the Welcome page.
[NOTE] If you are an existing Cloudimage customer and wish to be able to remove the v7 from your URL syntax, please contact our support.
The Ruby wrapper allows you to seamlessly interface the Cloudimage API.
Supported with Ruby 2.4+, JRuby and TruffleRuby
Installation
Add this line to your application's Gemfile:
gem 'cloudimage'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install cloudimage
Usage
The only requirement to get started is your customer token. You can find it within your Admin interface.
In order to interact with Cloudimage, we'll first initialise a client service object:
client = Cloudimage::Client.new(token: 'mysecrettoken')
The Cloudimage client accepts the following options:
option | type | additional info |
---|---|---|
token |
string | Required if cname is missing. |
cname |
string | Required if token is missing. See CNAME. |
salt |
string | Optional. See Security. Needed if you are using URL sealing or URL signatures. |
signature_length |
integer | Optional. Integer value in the range 6..40 . Defaults to 18. |
sign_urls |
boolean | Optional. Defaults to true. See Security. |
aliases |
hash | Optional. See URL aliases. |
Calling path on the client object returns an instance of Cloudimage::URI. It accepts path to the image as a string and we we will use it to build Cloudimage URLs.
uri = client.path('/assets/image.png')
Here are some common approaches for constructing Cloudimage URLs using this gem:
Hash of params
Pass a hash to to_url
. Every key becomes a param in the final Cloudimage URL so this gives you the freedom to pass arbitrary params if need be.
uri.to_url(w: 200, h: 400, sharp: 1, gravity: 'west', ci_info: 1)
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&gravity=west&h=400&sharp=1&w=200"
Chainable helpers
Every param supported by Cloudimage can be used as a helper method.
uri.w(200).h(400).gravity('west').to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?gravity=west&h=400&w=200"
While every key passed into to_url
method gets appended to the URL, chainable helper methods will throw a NoMethodError
when using an unsupported method.
uri.heigth(200).to_url
# NoMethodError (undefined method `heigth' for #<Cloudimage::URI:0x00007fae461c42a0>)
This is useful for catching typos and identifying deprecated methods in case Cloudimage's API changes.
Method aliases
The gem comes with a handful of useful aliases. Consult Cloudimage::Params module for their full list.
uri.debug.prevent_enlargement.to_url
# => "https://mysecrettoken.cloudimg.io/assets/image.png?ci_info=1&org_if_sml=1"
From the example above you can see that params that only serve as a flag don't need to accept arguments and will be translated into param=1
in the final URL.
For the full set of parameters and detailed implementation instructions, please consult the github page.