uploadcare-ruby 1.0.6 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7202dfd94679cd8f39df975484a50a6b1b8f7474
-  data.tar.gz: f53742f0245eae1002a6351afab310bcbdb3175d
+  metadata.gz: a64d207f7ef4f89a13f68834cea937420cc9f3a8
+  data.tar.gz: 4dfa8a074d60bc1a37651fb5c3f138799fe38154
 SHA512:
-  metadata.gz: 8f66ab85489edc1e08c87b63fb294cdff5dd382df5c5c80e531504dad1b7edaf8c16969448bbf721d9bf17f7af9175e3466cc7062feb2850af6f43b49903446c
-  data.tar.gz: c7ada37e8c0d23a9ffafe7dc9ce16f758e3ecafe092b0b099777e24f75c32ceccc13083464514edf1462898dddcc28ec920f427fa30079bb00e0a5324255300e
+  metadata.gz: b23740f26de3e0eeffdb832e431f0a4f739c089afb23f6e9d60a880e1ea2cb497e8288684c8abf96ee4a3daeaaeaea571723e18970fe979dbb1fea77dde4c07f
+  data.tar.gz: 4552d01fa016da894a2ed61e02f4ead93723b65faa76014ba61ef8af673fa20a61203831efe89e1aa552dfc3cdd39c3abe83622ea9ef93ce6f70e274a261f70f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 #Changelog
 
+### 1.1.0, 21.03.2017
+
+- Deprecated `Uploadcare::Api::File#copy` in favor of `#internal_copy` and `#external_copy`.
+- Added to new methods to Uploadcare::Api::File, #internal_copy and #external_copy.
+- Added support of [secure authorization](https://uploadcare.com/documentation/rest/#request) for REST API. It is now used by default (can be overriden in config)
+- Fixed middleware names that could break other gems ([#13](https://github.com/uploadcare/uploadcare-ruby/issues/13}).
+
 ### 1.0.6, 30.01.2017
 
 - Fixed incorrect dependencies

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Uploadcare, LLC
+Copyright (c) 2017 Uploadcare, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,42 +1,42 @@
 [![Build Status](https://secure.travis-ci.org/uploadcare/uploadcare-ruby.png?branch=master)](http://travis-ci.org/uploadcare/uploadcare-ruby)
 
-A ruby wrapper for [Uploadcare.com](https://uploadcare.com) service.
-
+A [Ruby](https://www.ruby-lang.org/en/) wrapper for [Uploadcare](https://uploadcare.com).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Installing `uploadcare-ruby` is quite simple and takes a couple of steps.
+First of, add the following line to your app's Gemfile:
 
 ```ruby
 gem 'uploadcare-ruby'
 ```
 
-And then execute:
+Once you've added the line, execute this:
 
 ```shell
 $ bundle install
 ```
 
-Or install it yourself:
+Or that (for manual install):
 
 ```shell
 $ gem install uploadcare-ruby
 ```
 
---
+## Initialization
 
-## Initalizations
-Just create an API object - and you're good to go.
+Init is simply done through creating an API object.
 
 ```ruby
 require 'uploadcare'
 
-@api = Uploadcare::Api.new #with default settings
+@api = Uploadcare::Api.new # default settings are used
 
-@api = Uploadcare::Api.new(settings)
+@api = Uploadcare::Api.new(settings) # using user-defined settings
 ```
 
-### Default settings 
+Here's how the default settings look like:
+
 ``` ruby
   {
     public_key: 'demopublickey',   # you need to override this
@@ -46,51 +46,42 @@ require 'uploadcare'
     static_url_base: 'https://ucarecdn.com',
     api_version: '0.3',
     cache_files: true,
+    auth_scheme: :secure
   }
 ```
 
-[Upload API](https://uploadcare.com/documentation/upload/) requires public key and [REST API](https://uploadcare.com/documentation/rest/) requires both public and private keys for authentication.  
-
-You can find and manage your project's API keys on project's overview page.
-Open [dashboard](https://uploadcare.com/dashboard/), click on the project's name and find "Keys" section.  
-
-If you haven't found what you were looking for in these docs, try looking in our [Knowledge Base](http://kb.uploadcare.com/).
-
---
-
-## Raw API
-Raw API is a simple interface that allows you to make custom requests to Uploadcare REST API.
-Just in case you want some low-level control over your app.
-
-```ruby
-# any request
-@api.request :get, "/files/", {page: 2}
-
-# you also have the shortcuts for methods
-@api.get '/files', {page: 2}
-
-@api.post ...
+You're free to use both `demopublickey` and `demoprivatekey`
+for initial testing purposes. We wipe out files loaded to our
+demo account periodically. For a better experience,
+consider creating an Uploadcare account. Check out
+[this](http://kb.uploadcare.com/article/234-uc-project-and-account)
+article to get up an running in minutes.
 
-@api.put ...
+Please note, in order to use [Upload API](https://uploadcare.com/documentation/upload/)
+you will only need the public key alone. However, using 
+[REST API](https://uploadcare.com/documentation/rest/) requires you to
+use both public and private keys for authentication.  
+While “private key” is a common way to name a key from an
+authentication key pair, the actual thing for our `auth-param` is `secret_key`.
 
-@api.delete ...
+## Usage
 
-```
-All raw API methods return parsed JSON response or raise an error (which you should handle yourself).
+This section contains practical usage examples. Please note,
+everything that follows gets way more clear once you've looked
+through our docs [intro](https://uploadcare.com/documentation/).
 
---
+### Basic usage: uploading a single file, manipulations
 
-## Basic usage
-Using Uploadcare is pretty easy (which is the essence of the service itself).
+Using Uploadcare is simple, and here are the basics of handling files.
 
-Create the API object:
+First of, create the API object:
 
 ```ruby
 @api = Uploadcare::Api.new(CONFIG)
 
 ```
 
-Upload file
+And yeah, now you can upload a file:
 
 ```ruby
 @file_to_upload = File.open("your-file.png")
@@ -99,62 +90,56 @@ Upload file
 # => #<Uploadcare::Api::File ...
 ```
 
-Use file
+Then, let's check out UUID and URL of the
+file you've just uploaded:
 
 ```ruby
-# file uuid (you probably want to store it somewhere)
+# file uuid (you'd probably want to store those somewhere)
 @uc_file.uuid
-# => "c969be02-9925-4a7e-aa6d-b0730368791c"
+# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
-# url for the file - just paste in your template and you good to go.
+# url for the file, can be used with your website or app right away
 @uc_file.cdn_url
-# => "https://ucarecdn.com/c969be02-9925-4a7e-aa6d-b0730368791c/"
+# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
 ```
 
-Store or delete file
+Your might then want to store or delete the uploaded file.
+Storing files could be crucial if you aren't using the
+“Automatic file storing” option for your Uploadcare project.
+If not stored manually or automatically, files get deleted
+within a 24-hour period.
 
 ```ruby
-# store file (if you dont use autostore option)
+# that's how you store a file
 @uc_file.store
 # => #<Uploadcare::Api::File ...
 
-# and delete file
+# and that works for deleting it
 @uc_file.delete
 # => #<Uploadcare::Api::File ...
 ```
-## Uploading
-You can upload either File object (array of files will also cut it) or custom URL.
 
-### Uploading from URL
-Just throw your URL into API - and you're good to go.
+### Uploading a file from URL
+
+Now, this one is also quick. Just pass your URL into our API
+and you're good to go.
 
 ```ruby
-# smart upload
+# the smart upload
 @file  = @api.upload "http://your.awesome/avatar.jpg" 
 # =>  #<Uploadcare::Api::File ...
 
-# explicitly upload from URL
+# use this one if you want to explicitly upload from URL
 @file = @api.upload_from_url "http://your.awesome/avatar.jpg" 
 # =>  #<Uploadcare::Api::File ...
 ```
-Keep in mind that invalid URL will raise an `ArgumentError`.
-
-### Uploading a single file
-Like with URL - just start throwing your file into API
-
-```ruby
+Keep in mind that providing invalid URL
+will raise `ArgumentError`.
 
-file = File.open("path/to/your/file.png")
-
-@uc_file  = @api.upload file
-# =>  #<Uploadcare::Api::File ...
-
-```
-And that's it.
+### Uploading multiple files
 
-### Uploading an array of files
-Uploading of an array is just as easy as uploading a single file.
-Note, that every object in array must be an instance of `File`.
+Uploading multiple files is as simple as passing an array
+of `File` instances into our API.
 
 ```ruby
 file1 = File.open("path/to/your/file.png")
@@ -162,22 +147,30 @@ file2 = File.open("path/to/your/another-file.png")
 files = [file1, file2]
 
 @uc_files = @api.upload files
-# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a">,
-#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6">]
+# => [#<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">,
+#     #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb">]
 ```
-It is returning you an array of Uploadcare files. 
+
+In case of multiple input, the respective output would also be an array.
+You can iterate through the array to address to single files.
+You might also want to request more info about a file using `load_data`.
 
 ```ruby
 @uc_files[0]
-# => #<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a">
+# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">
 
-@uc_files[0].load_data
-# => #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6", original_file_url="https://ucarecdn.com/7bb9efa4-05c0-4f36-b0ef-11a4221867f6/view.png", image_info={"width"=>800, "geo_location"=>nil, "datetime_original"=>nil, "height"=>600}, ....>
+@uc_files[1].load_data
+# => #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb", original_file_url="https://ucarecdn.com/96cdc400-adc3-435b-9c94-04cd87633fbb/samuelzeller118195.jpg", image_info={"width"=>4896, "geo_location"=>nil, "datetime_original"=>nil, "height"=>3264}, ....>
 ```
 
-## File
-`File` - is the primary object for Uploadcare API. Basically it's an avatar for file stored for you ).
-So all the operations you do - you do it with the file object.
+### `File` object
+
+Now that we've already outlined using arrays of `File` instances
+to upload multiple files, let's fix on the `File` itself.
+It's the the primary object for Uploadcare API.
+Basically, it's an avatar for a file you uploaded.
+And all the further operations are performed using this avatar,
+the `File` object.
 
 ```ruby
 @file_to_upload = File.open("your-file.png")
@@ -186,28 +179,32 @@ So all the operations you do - you do it with the file object.
 # => #<Uploadcare::Api::File ...
 
 @uc_file.uuid
-# => "c969be02-9925-4a7e-aa6d-b0730368791c"
+# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
 @uc_file.cdn_url
-# => "https://ucarecdn.com/c969be02-9925-4a7e-aa6d-b0730368791c/"
+# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
 ```
 
-There is one issue with files - all data associated with it accesible with separate HTTP request only.
-So if don't *specificaly* need image data (like file name, geolocation data etc.) - you could just use :uuid and :cdn_url methods for file output:
+Please note, all the data associated with files is only accessible
+through separate HTTP requests only. So if you don't specifically
+need file data (filenames, image dimensions, etc.), you'll be just
+fine with using `:uuid` and `:cdn_url` methods for file output:
 
 ```erb
 <img src="#{@file.cdn_url}"/>
 ```
 
-And that's it. Saves precious loading time.
-
-If you do however need image data - you could do it manualy:
+Great, we've just lowered a precious loading time.
+However, if you do need the data, you can always request
+it manually:
 
 ```ruby
 @uc_file.load_data
 ```
 
-Then your file object will respond to any method, described in API documentation (it basicaly an OpenStruct, so you know what to do):
+That way your file object will respond to any method described
+in [API docs](https://uploadcare.com/documentation/rest/#file).
+Basically, that's an an OpenStruct, so you know what to do:
 
 ```ruby
 @uc_file.original_filename
@@ -217,80 +214,253 @@ Then your file object will respond to any method, described in API documentation
 # => {"width"=>397, "geo_location"=>nil, "datetime_original"=>nil, "height"=>81}
 ```
 
-You could read more: https://uploadcare.com/documentation/rest/#file
+### `File` object from UUID or CDN URL
 
-### Generating files from stored info
-At this point you probably store your files UUIDs or CDN urls in some kind of storage.
-Then you can create file object by passing them into API:
+`File` objects are needed to manipulate files on our CDN.
+The usual case would be you as a client storing file UUIDs
+or CDN URLs somewhere on your side, e.g. in a database.
+This is how you can use those to create `File` objects:
 
 ```ruby
-# file by UUID
-@file = @api.file "c969be02-9925-4a7e-aa6d-b0730368791c"
-# => #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6"
+# file object from UUID
+@file = @api.file "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
+# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
-# file by CDN url
-@file = @api.file "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/"
-# => #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6"
+# file object from CDN URL
+@file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
+# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
-# not that generated files aren't loaded by initializing, you need to load it.
+# note, files you generate won't be loaded on init,
+# you'll need to load those manually
 @file.is_loaded?
 # => false
 ```
 
 ### Operations
-Uploadcare gives you some awesome CDN operations for croping, resizing, rotation, format convertation etc. You could read more at https://uploadcare.com/documentation/cdn/ .
-Version 1.0.0 of the gem has no specific methods for this kind of operations, we expect to add support for it later in 1.1 releases.
-For the moment all your file objects can store operations passed by cdn url:
+
+Another way to mainpulate files on CDN is through operations.
+This is particularly useful for images.
+We've got on-the-fly crop, resize, rotation, format conversions, and
+[more](https://uploadcare.com/documentation/cdn/).
+Image operations are there to help you build responsive designs,
+generate thumbnails and galleries, change formats, etc.
+Currently, this gem has no specific methods for image operations,
+we're planning to implement those in further versions.
+However, we do support applying image operations through
+adding them to CDN URLs. That's an Uploadcare CDN-native
+way described in our [docs](https://uploadcare.com/documentation/cdn/).
 
 ```ruby
-@file = @api.file "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/-/crop/150x150/center/-/format/png/"
-# => #<Uploadcare::Api::File uuid="a8775cf7-0c2c-44fa-b071-4dd48637ecac"
+@file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/-/crop/150x150/center/-/format/png/"
+# => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
 
 @file.operations
 # => ["crop/150x150/center", "format/png"]
 
-# note that by default :cdn_url method will return url without any operations:
+# note that by default :cdn_url method returns URLs with no operations:
 @file.cdn_url
-# => "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/""
+# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/""
 
-# you can pass true to :cdn_url methods to get url with included operations:
+# you can pass "true" into the :cdn_url method to get URL including operations:
 @file.cdn_url(true)
 # => "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/-/crop/150x150/center/-/format/png/"
 
-# or call specific methods for url with or without them:
+# there also are specific methods to either dump or include image operations
+# in the output URL:
 @file.cdn_url_with_operations
 @file.cdn_url_without_operations
 ```
 
-Until operations wrapper is released the best way for you to manage operation is simply add them to URL as a string:
+While there's no operation wrapper, the best way of handling operations
+is through adding them to URLs as strings:
 
 ```ruby
 <img src="#{file.cdn_url}-/crop/#{width}x#{height}/center/"/>
 # or something like that
 ```
 
-## File list and pagination
-File list is a paginated collection of files for you project. You could read more at https://uploadcare.com/documentation/rest/#pagination.
-In our gem file list is a single page containing 20 (by default, value may change) files and some methods for navigating through pages.
+### Copying files
+
+You can also create file copies using our API.
+There are multiple ways of creating those.
+Also, copying is important for image files because
+it allows you to “apply” all the CDN operations
+specified in the source URL to a separate static image.
+
+First of all, a copy of your file can be put in the Uploadcare storage.
+This is called “internal copy”, and here's how it works:
 
 ```ruby
-@list = @api.file_list 1 #page number, 1 by default
+@uc_file.internal_copy
+
+# =>
+{
+  "type"=>"file",
+  "result"=> {
+    "uuid"=>"a191a3df-2c43-4939-9590-784aa371ad6d",
+    "original_file_url"=>"https://ucarecdn.com/a191a3df-2c43-4939-9590-784aa371ad6d/19xldj.jpg",
+    "image_info"=>nil,
+    "datetime_stored"=>nil,
+    "mime_type"=>"application/octet-stream",
+    "is_ready"=>true,
+    "url"=>"https://api.uploadcare.com/files/a191a3df-2c43-4939-9590-784aa371ad6d/",
+    "original_filename"=>"19xldj.jpg",
+    "datetime_uploaded"=>"2017-02-10T14:14:18.690581Z",
+    "size"=>0,
+    "is_image"=>nil,
+    "datetime_removed"=>nil,
+    "source"=>"/4ea293d5-153f-422f-a24e-350237109606/"
+  }
+}
+```
+
+Once the procedure is complete, a copy would be a separate file
+with its own UUID and attributes.
+
+`#internal_copy` can optionally be used with the options hash argument.
+The available options are:
+
+- *store*
+
+  By default a copy is created without “storing”.
+  Which means it will be deleted within a 24-hour period.
+  You can make your output copy permanent by passing the
+  `store: true` option to the `#internal_copy` method.
+
+  Example:
+
+  ```ruby
+  @uc_file.internal_copy(store: true)
+  ```
+
+- *strip_operations*
+
+  If your file is an image and you applied some operations to it,
+  then by default the same set of operations is also applied to a copy.
+  You can override this by passing `strip_operations: true` to the
+  `#internal_copy` method.
+
+  Example:
+
+  ```ruby
+  file = @api.file "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"
+  file.internal_copy
+  # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"} in the body
+  file.internal_copy(strip_operations: true)
+  # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/"} in the body
+  ```
+
+Another option is copying your file to a custom storage.
+We call it “external copy” and here's the usage example:
+
+```ruby
+@uc_file.external_copy('my_custom_storage_name')
+
+# => 
+{
+  "type"=>"url",
+  "result"=>"s3://my_bucket_name/c969be02-9925-4a7e-aa6d-b0730368791c/view.png"
+}
+```
+
+First argument of the `#external_copy` method is a name of
+a custom destination storage for your file.
+
+There's also an optional second argument — options hash. The available options are:
+
+  - *make_public*
+
+  Make a copy available via public links. Can be either `true` or `false`.
+
+  - *pattern*
+
+  Name pattern for a copy. If the parameter is omitted, custom storage pattern is used.
+
+  - *strip_operations*
+
+  Same as for `#internal_copy`
+
+You might want to learn more about
+[storage options](https://uploadcare.com/documentation/storages/) or
+[copying files](https://uploadcare.com/documentation/rest/#files-post)
+with Uploadcare. 
+
+### `Group` object
+
+Groups are structures intended to organize sets of separate files.
+Each group is assigned UUID.
+Note, group UUIDs include a `~#{files_count}` part at the end.
+That's a requirement of our API.
+
+```ruby
+# group can be created from an array of Uploadcare files
+@files_ary = [@file, @file2]
+@files = @api.upload @files_ary
+@group = @api.create_group @files
+# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+
+# another way to from a group is via an array of strings holding UUIDs
+@uuids_ary = ["c969be02-9925-4a7e-aa6d-b0730368791c", "c969be02-9925-4a7e-aa6d-b0730368791c"]
+@group = @api.create_group @uuids_ary
+# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+
+# also, you can create a group object via group UUID
+@group_uloaded = @api.group "#{uuid}"
+```
+
+As with files, groups created via UUIDs are not loaded by default.
+You need to load the data manually, as it requires a separate
+HTTP GET request. New groups created with the `:create_group` method
+are loaded by default.
+
+```ruby
+@group = @api.group "#{uuid}"
+
+@group.is_loaded?
+# => false
+
+@group.load_data
+# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+
+# once a group is loaded, you can use any methods described in our API docs
+# the files within a loaded group are loaded by default
+@group.files
+# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
+#       ... #{files_count} of them ...
+#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
+```
+
+Check out our docs to learn more about
+[groups](https://uploadcare.com/documentation/rest/#group).
+
+### File lists and pagination
+
+File list is a paginated collection of files. Such lists are created
+to better represent the contents of your project.
+For this gem, a file list would be a single page containing
+20 files (you can override the number).
+There also are methods for navigating through pages.
+You can find more info about pagination
+[here](https://uploadcare.com/documentation/rest/#pagination).
+
+```ruby
+@list = @api.file_list 1 # page number, 1 is the default
 # => #<Uploadcare::Api::FileList ....
 
 
-# method :resulst will return you an array of files
+# method :results returns an array of files
 @list.results
 # => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
 #       ... 20 of them ...
 #     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
 
 
-# note that every file is already loaded
+# note, every file is already loaded
 @list.results[1].is_loaded?
 # => true
 
 
-# there is also shortcuts for you
+# we've also added some shortcuts
 @list.to_a
 # => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
 #       ... 20 of them ...
@@ -300,7 +470,7 @@ In our gem file list is a single page containing 20 (by default, value may chang
 # => #<Uploadcare::Api::File ....
 ```
 
-And don't forget that you can navigate throught pages:
+Here's how we handle navigating through pages:
 
 ```ruby
 @list = @api.files_list 3
@@ -314,9 +484,8 @@ And don't forget that you can navigate throught pages:
 @list.go_to 5
 # => #<Uploadcare::Api::FileList page=5 ....
 
-
-
-# there is also methods described in API docs avaliable for you:
+# of course, you can go with any of the methods
+# described in our API docs
 # total pages
 @list.pages
 # => 16
@@ -329,16 +498,16 @@ And don't forget that you can navigate throught pages:
 @list.per_page
 # => 20
 
-# total files in project
+# total files in a project
 @list.total
 # => 308
 ```
 
-## Project
-Project provides basic information about the connecting project.
-Project object is basicly openstruct so every method described in
-[API docs](https://uploadcare.com/documentation/rest/#project)
-accessible to you:
+### `Project` object
+
+`Project` provides basic info about the connected Uploadcare project.
+That object is also an OpenStruct, so every methods out of
+[these](https://uploadcare.com/documentation/rest/#project) will work.
 
 ```ruby
 project = @api.project
@@ -349,56 +518,42 @@ project.name
 
 p.collaborators
 # => []
-# more often it should look like
+# while that one was empty, it usually goes like this:
 # [{"email": collaborator@gmail.com, "name": "Collaborator"}, {"email": collaborator@gmail.com, "name": "Collaborator"}]
 ```
 
+### Raw API
 
-## Groups of files
-Groups of files - https://uploadcare.com/documentation/rest/#group.
-Stores files as group by the single UUID.
-Note that UUID has a `~#{files_count}` part at the end and it is required by API to work properly.
+Raw API is a simple interface allowing you to make
+custom requests to Uploadcare REST API.
+It's mainly used when you want a low-level control
+over your app.
 
 ```ruby
-# group can be created eather by array of Uploadcare Files:
-@files_ary = [@file, @file2]
-@files = @api.upload @files_ary
-@group = @api.create_group @files
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+# here's how you make any requests
+@api.request :get, "/files/", {page: 2}
 
-# or by array of strings containing UUIDs
-@uuids_ary = ["c969be02-9925-4a7e-aa6d-b0730368791c", "c969be02-9925-4a7e-aa6d-b0730368791c"]
-@group = @api.create_group @uuids_ary
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+# and there also are shortcuts for methods
+@api.get '/files', {page: 2}
 
-# you can also create group object just by passing group UUID
-@group_uloaded = @api.group "#{uuid}"
-```
+@api.post ...
 
-As with files, group created by passing just the UUID is not loaded by default - you need to load data manually, as it requires separate HTTP GET request.
-New groups created by :create_group method is loaded by default.
+@api.put ...
 
-```ruby
-@group = @api.group "#{uuid}"
+@api.delete ...
 
-@group.is_loaded?
-# => false
+```
 
-@group.load_data
-# => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
+All of the raw API methods return a parsed JSON response
+or raise an error (handling those is done on your side in the case).
 
-# loaded group has methods described by API docs and more importantly an array of files
-# this files are loaded by default.
-@group.files
-# => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
-#       ... #{files_count} of them ...
-#     #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
-```
+### Error handling
 
-## Errors handling
-From version 1.0.2 we have a custom exceptions which will raise when Uploadcare service return something with 4xx or 5xx HTTP status.
+Starting from the version 1.0.2, we've got have custom exceptions
+that will be raised in case the Uploadcare service returns
+something with 4xx or 5xx HTTP status.
 
-List of custom errors:
+Check out the list of custom errors:
 
 ```ruby
 400 => Uploadcare::Error::RequestError::BadRequest,
@@ -415,7 +570,8 @@ List of custom errors:
 504 => Uploadcare::Error::ServerError::GatewayTimeout
 ```
 
-so now you could escape particular error (in that case 404: Not Found error):
+That's how you handle a particular error
+(in this case, a “404: Not Found” error):
 
 ```ruby
 begin
@@ -425,7 +581,7 @@ rescue Uploadcare::Error::RequestError::NotFound => e
 end
 ```
 
-... any request error (covers all 4xx status codes): 
+Handling any request error (covers all 4xx status codes): 
 
 ```ruby
 begin
@@ -435,7 +591,7 @@ rescue Uploadcare::Error::RequestError => e
 end
 ```
 
-...and actually any Uploadcare service errors:
+Handling any Uploadcare service error:
 
 ```ruby
 begin
@@ -445,19 +601,37 @@ rescue Uploadcare::Error => e
 end
 ```
 
-Please note what almost all actions depends on Uploadcare servers and it will be wise of you to expect that servers will return error code (at least some times).
+Since many of the above listed things depend on Uploadcare servers,
+errors might occasionally occur. Be prepared to handle those.
 
 ## Testing
 
-Run `bundle exec rspec`.
+For testing purposes, run `bundle exec rspec`.
 
-To run tests with your own keys, make a `spec/config.yml` file like this:
+Please note, if you're willing to run tests using your own keys,
+make a `spec/config.yml` file containing the following:
 
 ```yaml
 public_key: 'PUBLIC KEY'
 private_key: 'PRIVATE KEY'
 ```
 
-## Contributing
+## Contributors
+
+This is open source so fork, hack, request a pull — get a discount.
+
+- [@romanonthego](https://github.com/romanonthego)
+- [@vizvamitra](https://github.com/vizvamitra)
+- [@dmitry-mukhin](https://github.com/dmitry-mukhin)
+- [@zenati](https://github.com/zenati)
+- [@renius](https://github.com/renius)
+
+## Security issues
+
+If you think you ran into something in Uploadcare libraries
+which might have security implications, please hit us up at
+[bugbounty@uploadcare.com](mailto:bugbounty@uploadcare.com)
+or Hackerone.
 
-This is open source, fork, hack, request a pull, receive a discount)
+We'll contact you personally in a short time to fix an issue
+through co-op and prior to any public disclosure.