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:
- Easy configuration for fast setup and use.
- A pre-defined class to help make any PORO a "sanity resource"
- Extensibility in overriding the wrapper of your API response results
- A small DSL around GROQ queries
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.