Strapi is an Open source Node.js Headless CMS to easily build customizable APIs. It’s great for quickly building your data layer alongside a UI to manage it.
Say you (like me) like to quickly build sites and applications in Ruby and/or/on Rails. The goal of the Strapi gem is to make it just as easy to define Ruby classes that represent and interact with your Strapi content types as it is to define them within Strapi itself.
Add this line to your application's Gemfile:
Or if you want to run the absolute latest, potentially unreleased version:
gem 'strapi', github: 'waymondo/strapi-ruby'
And then execute:
$ bundle install
This gem has only been tested with Strapi v4. It may work with previous versions of Strapi, but they remain untested at this time.
You will first need to set an
ENV variable for
latter is only required if accessing content types requires authentication). This can be done with
dotenv, in an initializer, or some other mechanism.
.env file would contain:
Defining Content Type Classes
In Ruby, define some content type classes, i.e.:
class Farm < Strapi::ContentType field :name field :cows, content_type: 'Cow' field :photo, content_type: 'Strapi::Media' end
class Cow < Strapi::ContentType field :name field :farm, content_type: 'Farm' end
field class method will define getter and setter methods for the class objects. If you
supply a class name to the
content_type option, it will transform it to an instance of that class
when using the getter method. This works for both one-to-one and one-to-many relations:
cow.name # => "Hershey" cow.farm # => #<Farm> farm.name # => "McDonald’s" farm.cows # => [#<Cow>, #<Cow>]
In keeping with ruby conventions, attribute keys returned from your Strapi API will be underscored,
so if you have an attribute of
"colorPattern": "jersey" in your JSON, your field definition should
Strapi::Media is an
included content type class to represent photos, videos, and files. Feel free to extend this class
if you would like to add additional functionality or granularity.
farm.photo # => #<Strapi::Media> farm.photo.url # => "http://localhost:1337/uploads/farm-1.jpg"
Strapi::ContentType will infer it’s API plural id from the demodulized, dasherized,
pluralized name of the ruby class. For example, it would assume a class of
FarmWorker would have a
Strapi plural ID of
farm-workers. If you would like to customize this, you can set it in the class
class FarmWorker plural_id 'farmers' end
Strapi::ContentType provides some predictable methods for retrieving entries from your Strapi API:
Cow.all # => [#<Cow>, #<Cow>, #<Cow>] cow = Cow.find(1) cow.id # => 1
.find accept a hash of options that map to Strapi’s allowed API
parameter options are included by default, so if you want to eagerly load related content types for
example, you’ll need to specify that with the
cows = Cow.all(populate: '*') cows.first.farm.name # => "McDonald’s" farm = Farm.find(1, populate: ['cows']) farm.cows.first.name # => "Hershey"
The class method
.where also exists, which is the same implementation as
.all, except a hash of
API parameters is required.
Creating, Updating, Deleting
You can create and update entries by calling
.save on them:
cow = Cow.new(name: 'Hershey') cow.id # => nil cow.save # => performs POST request cow.id # => 1 cow = Cow.find(1) cow.name = 'Bessie' cow.save # => performs PUT request
You can also use
create class method to more concisely create entries:
cow = Cow.create(name: 'Bessie') cow.id # => 1
You can delete entries by calling
.delete on them:
cow = Cow.find(1) cow.delete # => performs DELETE request cow = Cow.find(1) # => raises Strapi::Error
Any non successful Strapi request will raise a Strapi::Error with the API response’s status, message, and payload, which you can rescue and handle accordingly:
def show cow = Cow.find(123) render :cow, cow: cow rescue Strapi::Error => e render :error, message: e.message end
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake test to run
the tests. You can also run
bin/console for an interactive prompt that will allow you to
To install this gem onto your local machine, run
bundle exec rake install. To release a new
version, update the version number in
version.rb, and then run
bundle exec rake release, which
will create a git tag for the version, push git commits and the created tag, and push the
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/waymondo/strapi-ruby.
The gem is available as open source under the terms of the MIT License.