Morning Brew
Morning Brew Engineering
Ruby Library for the Sanity API
The Sanity Ruby library provides convenient access to the Sanity API from applications written in Ruby. It includes a pre-defined set of classes for API resources.
The library also provides other features, like:
Add this line to your application's Gemfile:
gem 'sanity-ruby'
Setup your configuration. If using in Rails, consider setting this in an initializer:
Sanity.configure do |s| s.token = "yoursupersecrettoken" s.api_version = "v2021-03-25" s.project_id = "1234" s.dataset = "development" s.use_cdn = false end
To create a new document:
Sanity::Document.create(params: {_type: "user", first_name: "Carl", last_name: "Sagan"})
You can also return the created document ID.
res = Sanity::Document.create(params: {_type: "user", first_name: "Carl", last_name: "Sagan"}, options: {return_ids: true}) # JSON.parse(res.body)["results"] # > [{"id"=>"1fc471c6434fdc654ba447", "operation"=>"create"}]
To create a new asset:
# TODO
To make any PORO a sanity resource:
class User < Sanity::Resource attribute :_id, default: "" attribute :_type: default: "" mutatable only: %i(create delete) queryable end
To create a new document in Sanity:
User.create(params: { first_name: "Carl", last_name: "Sagan" })
or if you need to validate the object in your application first:
user = User.new(first_name: "Carl", last_name: "Sagan") # your business logic here... user.create
To make any PORO act like a sanity resource:
class User include Sanity::Mutatable include Sanity::Queryable queryable mutatable end
Sanity::Document.create(params: {_type: "user", first_name: "Carl", last_name: "Sagan"})
To create or replace a document:
Sanity::Document.create_or_replace(params: { _id: "1234-321", _type: "user", first_name: "Carl", last_name: "Sagan"})
To create a document if it does not exist:
Sanity::Document.create_if_not_exists(params: { _id: "1234-321", _type: "user", first_name: "Carl", last_name: "Sagan"})
Sanity::Document.delete(params: { _id: "1234-321"})
To patch a document:
Sanity::Document.patch(params: { _id: "1234-321", set: { first_name: "Carl" }})
Sanity::Document.find(_id: "1234-321")
To find documents based on certain fields:
majority supported
where: { _id: "123", # _id == '123' _id: {not: "123"} # _id != '123' title: {match: "wo*"} # title match 'wo*' popularity: {gt: 10}, # popularity > 10 popularity: {gt_eq: 10}, # popularity >= 10 popularity: {lt: 10}, # popularity < 10 popularity: {lt_eq: 10}, # popularity <= 10 _type: "movie", or: {_type: "cast"} # _type == 'movie' || _type == 'cast' _type: "movie", and: {or: [{_type: "cast"}, {_type: "person"}]} # _type == 'movie' && (_type == 'cast' || _type == 'person') _type: "movie", or: [{_type: "cast"}, {_type: "person"}] # _type == 'movie' || _type == 'cast' || _type == 'person' }
Sanity::Document.where(_type: "user", and: {or: {_id: "123", first_name: "Carl" }}) # Resulting GROQ: # *[_type == 'user' && (_id == '123' || first_name == 'Carl')]
partially supported
order: { createdAt: :desc, updatedAt: :asc } # order(createdAt desc) | order(updatedAt asc)
limit: 5, offset: 10
Sanity::Document.where(_type: "user", limit: 5, offset: 2)
partially supported
select: [:_id, :slug, :title, :name]
Sanity::Document.where(_type: "user", select: %i[first_name last_name])
Should you need more advanced querying that isn't handled in this gem's DSL you can pass a raw groq query
groq_query = <<-GROQ *[ _type =='movie' && name == $name] { title, poster { asset-> { path, url } } } GROQ Sanity::Document.where(groq: groq_query, variables: {name: "Monsters, Inc."})
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
.
Bug reports and pull requests are welcome on GitHub at https://github.com/morning-brew/sanity-ruby.
The gem is available as open source under the terms of the MIT License.
gem install sanity-ruby
Morning Brew Engineering