CDN Connect makes it easier to manage production assets for teams of developers and designers, all while serving files from a fast content delivery network. Features include image optimization, resizing, cropping, filters, changing output formats, convert to WebP image format, etc. The CDN Connect API Ruby Client makes it easier to upload files and interact with the API with only a few lines of code.
View the full CDN Connect API documentation
$ gem install cdnconnect-api
First step is to create an api client instance which will be used to connect to your CDN Connect app. The required options are app_host and api_key.
The CDN Connect App host includes your app subdomain and the cdnconnect.com domain. For example, demo.cdnconnect.com is a CDN Connect app host. The app host should not include https://, http:// or a URL path such as /images.
Most interactions with CDN Connect APIs require users to authorize applications via OAuth 2.0. An API Key can be created for a specific app within your CDN Connect's account. Sign into your account and go to the "API Key" tab for the app you want to interact with. Next click "Add API Key" and use this value when creating a new API client within the code. The API Key can be revoked by you at any time and numerous keys can be created.
require 'cdnconnect_api'
api_client = CDNConnect::APIClient.new(:app_host => 'YOUR_APP.cdnconnect.com',
:api_key => 'YOUR_API_KEY')
Upload a file or multiple files from a local machine to a folder within a CDN Connect app. The upload method provides numerous ways to upload files or files, to include recursively drilling down through local folders and uploading only files that match your chosen extensions. If any of the folders within the upload path do not already exist then they will be created automatically.
Below are the possible parameters for the upload method. You must set destination_path and use one of the options to select where the source files are uploaded from.
destination_path: The URL of the CDN Connect folder to upload to. If the destination folder does not already exist it will automatically be created.source_file_path: A string of a source file's local path to upload to the destination folder. If you have more than one file to upload it'd be better to usesource_file_pathsorsource_folder_pathinstead.source_file_paths: A list of a source file's local paths to upload. This option uploads all of the files to the destination folder. If you want to upload files in a local folder thensource_folder_pathoption may would be easier than listing out files manually.source_folder_path: A string of a source folder's local path to upload. This will upload all of the files in this source folder to the destination url. By using thevalid_extensionsparameter you can also restrict which files should be uploaded according to extension.valid_extensions: An array of valid extensions which should be uploaded. This is only applied when thesource_folder_pathoptions is used. If nothing is provided, which is the default, all files within the folder are uploaded. The extensions should be in all lower case, and they should not contain a period or asterisks. Examplevalid_extensions => ['js', 'css', 'jpg', jpeg', 'png', 'gif', 'webp']recursive_local_folders: A true or false value indicating if this call should recursively upload all of the local folder's sub-folders, and their sub-folders, etc. This option is only used when thesource_folder_pathoption is used.destination_file_name: The name which the uploaded file should be renamed to. By default the file name will be the same as the file being uploaded. Thedestination_file_nameoption is only used for a single file upload, it does not work for multiple file requests.queue_processing: A true or false value indicating if the processing of the data should be queued or processed immediately. A response with "queued_processing" will be faster because the resposne doesn't wait on the system to complete processing the data. However, because an queued processing response does not wait for the data to complete processing then the response will not contain any information about the data which was just uploaded. Use queued processing only if you do not need to know the details of the upload. Additionally you can use thewebhook_urlto post back the uploads details once it's processed. Default is true.webhook_url: A URL which the system shouldPOSTthe response to. This works for both immediate processing or queued processing calls. The data sent to thewebhook_urlwill be the same as the data that is responded in a synchronous response, and is sent within thedataparameter. The format sent can be in eitherjsonorxmlby using thewebhook_formatparameter. By default there is no webhook URL.webhook_format: When awebhook_urlis provided, you can have the data formatted as eitherjsonorxml. The defautl format isjson.
Use this option if you simply want to upload just one file. If you have many files to upload we recommend using either source_file_paths or source_folder_path.
response = api_client.upload(:destination_path => '/images',
:source_file_path => '/Users/Ellie/Pictures/meowzers.jpg')
Specify a list of local files that should be uploaded to an app folder. Use this option if you want to manually select which files should be uploaded. Use the source_folder_path option if you want to easily upload all of the files
in a folder.
response = api_client.upload(:destination_path => '/images/kitty',
:source_file_paths => [
'/Users/Ellie/Pictures/furball.jpg',
'/Users/Ellie/Pictures/smuckers.jpg',
'/Users/Ellie/Pictures/socks.jpg'
])
All files within the local Pictures folder will be uploaded. Additionally, by default all files within its subfolders will also be uploaded. Refer to the recursive_local_folders parameter if you do not want to recursively upload files in subfolders.
response = api_client.upload(:destination_path => '/images/',
:source_folder_path => '/Users/Ellie/Pictures/')
Both files and folders are considered "objects", and object data contains information stating if it is a file or a folder. A folder can contain many sub-folders, and many files, and a file is contained by a folder. The concept of files and folders is no different than how your computer handles them, and their hierarchy is what builds the URL. Getting information about a file or a folder both use get_object.
response = api_client.get_object(:path => '/images/spacewalk.jpg')
response = api_client.get_object(:path => '/images')
response = api_client.get_object(:path => '/images', :files => true, :folders => true)
Renames a file or folder, which are both also known as an object.
response = api_client.rename_object(:path => '/images/tv-shows/night-rider.jpeg',
:new_name => 'knight-rider.jpg')
Creates a folder structure according to the path provided. If any of the folders do not already exist they will be created. The response contains data for every folder in the path, new and existing. The feature of creating the path automatically is also available when uploading files.
In the example below, if the folders images or movies did not already exist with the CDN Conenct app then they would automatically be created.
response = api_client.create_path(:path => '/images/movies')
HTTP responses will be formatted in json, but the library takes the HTTP response and decodes into a hash for the APIResponse class. The APIResponse class is used to simpilfy things by using helper functions to read response data. Responses from the API are all structured the same way, and this class is used as a small wrapper to make it easier to get data from it. Note: Be sure to set the :queue_processing => false upload option if you would like to get the upload info the upload's response.
files:array: A list of all the files that were uploaded. Each file in the array is a hash.object:hash: Can be either a file or folder, or the first file in thefilesarray.msgs:array: An array of messages, and each message is a hash. Example message within themsgsarray:{"text" => "info about the message", "status" => "error"}is_success:bool: Successful API call, the response should contain the data your looking for.is_error:bool: Unsuccessful API call. Could be a client error (400) or a server error (500).is_client_error:bool: Unsuccessful API call due to a client error. Review themsgsarray for more info.is_bad_request:bool: Unsuccessful API call due to sending invalid data. Review themsgsarray for more info.is_unauthorized:bool: Unsuccessful API call due to not being authorized.is_not_found:bool: Unsuccessful API call because the resource does not exist.is_server_error:bool: Unsuccessful API call because server is having issues (its also possible, but hopefully you'll never see this).
if response.is_success
# Be sure to set the :queue_processing => false upload option if you would like to get the upload info like the response below
for file in response.files
puts "Uploaded " + file["name"]
end
end
if response.is_success
puts "Got object " + response.object["name"]
end
if response.is_error
puts "CDN Connect Error"
for msg in response.msgs
puts msg["status"] + ": " + msg["text"]
end
end
Note that this HTTP response will be parsed and can be easily read using the APIResponse. Be sure to view the API documentation describing what each response object will contain depending on the API resource.
Please report any bugs on this project's issues page. Additionally, please don't hesitate to contact us and/or submit a pull request with any ideas you may have to improve the service. We will continue to improve upon and build out the API in order to bring more value to you and your projects.