Ruby on Rails API client

Ruby on Rails integration handles uploads and file operations by wrapping uploadcare-ruby gem. It will let you use most of the Uploadcare features from within your Ruby on Rails app.

Gem →

GitHub →

Features

Gem features:

• File uploader
• Image processing
• Uploadcare API interfaces

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 3.3+
• Ruby on Rails 7.2+

Install

Using Gemfile

Add this line to your application’s Gemfile:

1
gem "uploadcare-rails", "~> 5.0"

And then execute:

1
bundle install

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

1
gem 'uploadcare-api_struct'

and run bundle install.

Using command line

1
gem install uploadcare-rails

Usage

Configuration

To start using Uploadcare API you just need to set your API keys (public key and secret key). These keys can be set as ENV variables using the export directive:

1
export UPLOADCARE_PUBLIC_KEY=YOUR_PUBLIC_KEY
2
export UPLOADCARE_SECRET_KEY=YOUR_SECRET_KEY

Or you can use popular gems like dotenv-rails for setting ENV variables. You must set the gem before uploadcare-rails like this:

1
gem "dotenv-rails", require: "dotenv/rails-now", groups: [:development, :test]
2
gem "uploadcare-rails", "~> 5.0"

Run the config generator command to generate a configuration file:

1
rails g uploadcare_config

The generator will create a new file at config/uploadcare.yml.

The public key must be specified to use File Upload. For an ENV-based setup, keep the environment sections and set the keys in config/uploadcare.yml:

1
# config/uploadcare.yml
2
default: &default
3
  public_key: <%= ENV.fetch("UPLOADCARE_PUBLIC_KEY") %>
4
  secret_key: <%= ENV.fetch("UPLOADCARE_SECRET_KEY") %>
5
  store_files_after_save: true
6
  delete_files_after_destroy: true
7
  cache_files: true
8
  locale: en
9
10
development:
11
  <<: *default
12
13
test:
14
  <<: *default
15
16
production:
17
  <<: *default

You can also configure programmatically in an initializer:

1
Uploadcare::Rails.configure do |config|
2
  config.public_key = ENV.fetch("UPLOADCARE_PUBLIC_KEY")
3
  config.secret_key = ENV.fetch("UPLOADCARE_SECRET_KEY")
4
  config.store_files_after_save = true
5
  config.delete_files_after_destroy = true
6
  config.cache_files = true
7
  config.locale = "en"
8
end

Then you can configure all global variables such as files storing/caching, deleting files, etc. Full list of available options is listed in the file itself.

Model

Use has_uploadcare_file for a single file and has_uploadcare_files for a group of files:

1
class Post < ApplicationRecord
2
  has_uploadcare_file :picture
3
  has_uploadcare_files :attachments
4
end

View

Add the File Uploader to your layout:

1
<%= uploadcare_include_tag %>

Use the form helpers to render file upload fields:

1
<%= form_with model: @post do |f| %>
2
  <%= f.uploadcare_file_field :picture %>
3
  <%= f.uploadcare_files_field :attachments %>
4
<% end %>

REST API

Access the Uploadcare REST API directly via the client:

1
client = Uploadcare::Rails.client
2
3
# Get file info
4
file = client.files.find(uuid: "YOUR_FILE_UUID")
5
6
# Store a file
7
client.files.batch_store(uuids: ["YOUR_FILE_UUID"])
8
9
# Delete a file
10
client.files.batch_delete(uuids: ["YOUR_FILE_UUID"])

Full documentation

Read the full documentation on GitHub.