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:
gem 'strapi'
Or if you want to run the absolute latest, potentially unreleased version:
gem 'strapi', github: 'waymondo/strapi-ruby'
And then execute:
$ bundle install
Note: 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 STRAPI_HOST_URL
, STRAPI_IDENTIFIER
and
STRAPI_PASSWORD
. This can be done with dotenv
, in an
initializer, or some other mechanism.
If using dotev
, your .env
file would contain:
STRAPI_HOST_URL=https://localhost:1337
[email protected]
STRAPI_PASSWORD=password
The STRAPI_IDENTIFIER
and STRAPI_PASSWORD
should be the login information for a user with a role
that grants access to your authenticated content. Strapi Authenticated request
documentation
Upon running the first method that interacts with the Strapi API, a JWT token will be fetched and cached.
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
Using the 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
be field :color_pattern
.
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 # => "https://localhost:1337/uploads/farm-1.jpg"
By default, 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
definition:
class FarmWorker
plural_id 'farmers'
end
Strapi default timestamps fields (created_at
, updated_at
, published_at
) are automatically converted
into DateTime
objects and do not need to be added with field
declarations.
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
Both .all
and .find
accept a hash of options that map to Strapi’s allowed API
parameters. No
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 populate
option:
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.
cows = Cow.where(filters: { name: { '$eq': 'Hershey' } })
In order to paginate results, you can have to provide the Strapi's API pagination parameters, it will return an
Strapi::CollectionContentType
object with the following convenience methods:
farms = Farm.all(pagination: { page: 1, pageSize: 10 })
# Collection's methods
farms.size # => 10 # or count
farms.has_next_page? # => true
farms.first # => #<Farm>
# Pagination's methods
farms.pagination.page # => 1
farms.pagination.page_size # => 10
farms.pagination.page_count # => 5
farms.pagination.total # => 45
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
experiment.
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 .gem
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.