README.md in cdnconnect-api-0.1.2 vs README.md in cdnconnect-api-0.2.0

- old
+ new

@@ -1,83 +1,161 @@ -# CDN Connect API Ruby Client, v0.1.2 +# CDN Connect API Ruby Client, v0.2.0 -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, etc. The CDN Connect API Ruby Client makes it easier to upload files and interact with the API. Most interactions with CDN Connect APIs require users to authorize applications via OAuth 2.0. This library simplifies the communication with CDN Connect even further allowing you to easily upload files and get information with only a few lines of code. +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](http://api.cdnconnect.com/) ## Install $ gem install cdnconnect-api [RubyGems.org: cdnconnect-api](https://rubygems.org/gems/cdnconnect-api) -## API Key +## Setup the API Client -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. +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`. +#### App Host +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`. -## Upload Example +#### API Key - # Initialize the CDN Connect API client +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. + + +#### Example API Client + require 'cdnconnect_api' - api_client = CDNConnect::APIClient.new(:api_key => YOUR_API_KEY) + + api_client = CDNConnect::APIClient.new(:app_host => 'YOUR_APP.cdnconnect.com', + :api_key => 'YOUR_API_KEY') + + +## Upload Files + +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 use `source_file_paths` or `source_folder_path` instead. + - `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 then `source_folder_path` option 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 the `valid_extensions` parameter 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 the `source_folder_path` options 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. Example `valid_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 the `source_folder_path` option is used. + - `async` : A true or false value indicating if the processing of the data should be asynchronous or not. The default value is false meaning that the processing of the data will be synchronous. An async response will be faster because the resposne doesn't wait on the system to complete processing the data. However, because an async 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 async only if you do not need to know the details of the upload. + - `webhook_url` : A URL which the system should `POST` the response to. This works for both synchronous and asynchronous calls. The data sent to the `webhook_url` will be the same as the data that is sent in a synchronous response. By default there is not webhook URL. + +### Upload One File: `source_file_path` + +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') - # Upload to a folder in the app the API Key was created for - response = api_client.upload(:destination_folder_url => 'demo.cdnconnect.com/images', - :source_file_local_path => 'meowzers.jpg') +### Upload A List Of Files: `source_file_paths` + +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' + ]) + +### Upload All Of The Files In The Folder: `source_folder_path` + +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/') - # Read the response + +## Get File or Folder Information + +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`. + + +#### Get File Information + + response = api_client.get_object(:path => '/images/spacewalk.jpg') + + +#### Get Folder Information + + response = api_client.get_object(:path => '/images') + + +## Rename File or Folder + +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') + + +## Create A Folder Path + +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') + + +## API Response + +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. + + + - `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 the `files` array. + - `msgs ` : `array` : An array of messages, and each message is a hash. Example message within the `msgs` array: `{"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 the `msgs` array for more info. + - `is_bad_request` : `bool` : Unsuccessful API call due to sending invalid data. Review the `msgs` array 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). + + +#### Example Upload Response + if response.is_success - # "Woot!" - end + for file in response.files + puts "Uploaded " + file["name"] + end -## API Requests + end -Following the [API documentation](http://api.cdnconnect.com/), you can use these methods to build a requests and return an APIResponse object. -* `get` GET Request. Used when needing to just read data. -* `post` POST Request. Used when creating data. -* `put` PUT Request. Used when updating data. -* `delete` DELETE Request. Used when deleting data. +#### Example Get Object Response -Each of these methods take one parameter which is the API path you want to request. Depending on which method you use, it will send the request with the correct HTTP verb. + if response.is_success - response = api_client.get('/v1/demo.cdnconnect.com/images/meowzers.jpg.json') - puts response.results['object']['name'] #=> "meowzers.jpg" + puts "Got object " + response.object["name"] -The path in the API request is broken down as: + end -* `/v1/` The API version, which must always prefix an API request path. -* `demo.cdnconnect.com/images/meowzers.jpg` The URL which you want to get information about. -* `.json` The response format, which can be `json` or `xml`. +#### Example Error Response -## Response Object + if response.is_error -All responses will be structured the same with both a `results` and `msgs` object at the root level, such as: + puts "CDN Connect Error" - { - "results": - { - "object": - { - "id": "bU1SS1JyvF9I", - "status": 1, - "name": "images", - "created": "2013-03-12T17:02Z", - "parent_id": "iF637hnbwI4G", - "folder": true, - "files": [], - "folders": [] - } - }, - "msgs":[] - } + for msg in response.msgs + puts msg["status"] + ": " + msg["text"] + end -Be sure to view the [API documentation](http://api.cdnconnect.com/) describing what each response object will contain depending on the API resource. + end + +Note that this HTTP response will be parsed and can be easily read using the APIResponse. Be sure to view the [API documentation](http://api.cdnconnect.com/) describing what each response object will contain depending on the API resource. ## Support Please [report any bugs](https://github.com/cdnconnect/cdnconnect-api-ruby/issues) 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.