Ruby API Client

Ruby integration handles uploads and file operations by wrapping Uploadcare Upload API and REST API. This comprehensive API client lets you use most of the Uploadcare features from within your Ruby app.

Gem →

GitHub →

Features

Uploading (Upload API):

  • Upload files from local storage and URLs (up to 5 TB)
  • Multipart uploading for large files
  • Uploading network to speed uploading jobs (like CDN)

File management (REST API):

  • Get file info and perform various operations (store/delete/copy) with them
  • Work with groups of files
  • Get info about account project
  • Manage webhooks
  • Convert documents
  • Encode and transform videos

Image processing (URL API):

  • Compression
  • Geometry
  • Colors
  • Definition
  • Image and text overlays
  • Rotations
  • Recognition
  • File info
  • Proxy (fetch)

Security features:

  • Secure authentication
  • Secure uploads (signed uploads)
  • Secure delivery (signed URLs)
  • Secure webhooks (signing secret)

Requirements

  • Ruby 2.7+

Note that uploadcare-ruby 3.x is not backward compatible with 2.x.

Install

Add this line to your application’s Gemfile:

1gem 'uploadcare-ruby'

And then execute:

bundle

If you use api_struct gem in your project, replace it with uploadcare-api_struct:

gem 'uploadcare-api_struct'

and run bundle install.

If already not, create your project in Uploadcare dashboard and copy your API keys from there.

Set your Uploadcare keys in config file or through environment variables:

$export UPLOADCARE_PUBLIC_KEY=$YOUR_PUBLIC_KEY
>export UPLOADCARE_SECRET_KEY=$YOUR_SECRET_KEY

Or configure your app yourself if you are using different way of storing keys. Gem configuration is available in Uploadcare.configuration. Full list of settings can be seen in lib/uploadcare.rb

1# your_config_initializer_file.rb
2Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
3Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'

Usage example

This section contains practical usage examples. Please note, everything that follows gets way more clear once you’ve looked through our docs.

Uploading and storing a single file

Using Uploadcare is simple, and here are the basics of handling files.

1@file_to_upload = File.open("your-file.png")
2
3@uc_file = Uploadcare::Uploader.upload(@file_to_upload)
4
5@uc_file.uuid
6# => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
7
8# URL for the file, can be used with your website or app right away
9@uc_file.cdn_url
10# => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"

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.

1# that's how you store a file
2@uc_file.store
3# => #<Uploadcare::Api::File ...
4
5# and that works for deleting it
6@uc_file.delete
7# => #<Uploadcare::Api::File ...

Uploads

Uploadcare supports multiple ways to upload files:

1# Smart upload - detects type of passed object and picks appropriate upload method
2Uploadcare::Uploader.upload('https://placekitten.com/96/139')

There are explicit ways to select upload type:

1files = [File.open('1.jpg'), File.open('1.jpg']
2Uploadcare::Uploader.upload_files(files)
3
4Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
5
6# multipart upload - can be useful for files bigger than 10 mb
7Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))

Upload options

You can override global :autostore option for each upload request:

1@api.upload(files, store: true)
2@api.upload_from_url(url, store: :auto)

Api

Most methods are also available through Uploadcare::Api object:

1# Same as Uploadcare::Uploader.upload
2Uploadcare::Api.upload('https://placekitten.com/96/139')

Entity object

Entities are representations of objects in Uploadcare cloud.

File

File entity contains its metadata.

1@file = Uploadcare::File.file('FILE_ID_IN_YOUR_PROJECT')
2{"datetime_removed"=>nil,
3 "datetime_stored"=>"2020-01-16T15:03:15.315064Z",
4 "datetime_uploaded"=>"2020-01-16T15:03:14.676902Z",
5 "image_info"=>
6  {"color_mode"=>"RGB",
7   "orientation"=>nil,
8   "format"=>"JPEG",
9   "sequence"=>false,
10   "height"=>183,
11   "width"=>190,
12   "geo_location"=>nil,
13   "datetime_original"=>nil,
14   "dpi"=>nil},
15 "is_image"=>true,
16 "is_ready"=>true,
17 "mime_type"=>"image/jpeg",
18 "original_file_url"=>
19  "https://ucarecdn.com/FILE_ID_IN_YOUR_PROJECT/imagepng.jpeg",
20 "original_filename"=>"image.png.jpeg",
21 "size"=>5345,
22 "url"=>
23  "https://api.uploadcare.com/files/FILE_ID_IN_YOUR_PROJECT/",
24 "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
25
26@file.copy #copies file, returns a new (copied) file metadata
27
28@file.store #stores file, returns updated metadata
29
30@file.delete #deletes file. Returns updated metadata

Metadata of deleted files is stored permanently.

FileList

Uploadcare::Entity::FileList represents the whole collection of files (or it’s subset) and provides a way to iterate through it, making pagination transparent. FileList objects can be created using Uploadcare::Entity.file_list method.

1@list = Uploadcare::Entity.file_list
2# Returns instance of Uploadcare::Api::FileList
3<Hashie::Mash
4  next=nil
5  per_page=100
6  previous=nil
7  results=[
8    # Array of Entity::File
9  ]
10  total=8>
11# load last page of files
12@files = @list.files
13# load all files
14@all_files = @list.load

Full documentation

Read the full documentation on GitHub.