Lurch
A simple Ruby JSON API client.
Installation
Add this line to your application's Gemfile:
gem "lurch", "~> 0.2"
And then execute:
$ bundle
Or install it yourself:
$ gem install lurch
Basic Usage
Start by creating a store:
store = Lurch::Store.new("http://example.com/api")Fetch resources from the server
GET individual resources from the server by id:
person = store.from(:people).find("1")
#=> #<Lurch::Resource[Person] id: "1", name: "Bob">Or GET all of them at once:
people = store.from(:people).all
#=> [#<Lurch::Resource[Person] id: "1", name: "Bob">, #<Lurch::Resource[Person] id: "2", name: "Alice">]Lurch::Resource objects have easy accessors for all attributes returned from the server:
person.name
#=> "Bob"
person[:name]
#=> "Bob"
person.attributes[:name]
#=> "Bob"But, Lurch::Resource objects are immutable:
person.name = "Robert"
#=> NoMethodError: undefined method `name=' for #<Lurch::Resource:0x007fe62c848fb8>Update existing resources
To update an existing resource, create a changeset from the resource, then PATCH it to the server using the store:
changeset = Lurch::Changeset.new(person, name: "Robert")
store.save(changeset)
#=> #<Lurch::Resource[Person] id: "1", name: "Robert">Existing references to the resource will be updated:
person.name
#=> "Robert"Create new resources
To create new resources, first create a changeset, then POST it to the server using the store:
changeset = Lurch::Changeset.new(:person, name: "Carol")
new_person = store.insert(changeset)
#=> #<Lurch::Resource[Person] id: "3", name: "Carol">Filtering
You can add filters to your request if your server supports them:
people = store.from(:people).filter(name: "Alice").all
#=> [#<Lurch::Resource[Person] id: "2", name: "Alice">]Other query parameters
You can add arbitrary parameters as well. Note that your server should adhere to JSON:API's query parameter constraints.
people = store.from(:people).params(someQuery: "blue").all
# => GET /people?someQuery=blueRelationships
Lurch can fetch has-many and has-one relationships from the server when they are provided as related links:
person = store.from(:people).find("1")
person.hobbies
#=> #<Lurch::Relationship::Linked href: "http://example.com/api/people/1/friends">
person.hobbies.fetch
#=> #<Lurch::Collection[Hobby] size: 2, pages: 1>
person.best_friend
#=> #<Lurch::Relationship::Linked href: "http://example.com/api/people/1/best-friend">
person.best_friend.fetch
#=> #<Lurch::Resource[Person] id: "2", name: "Alice">If the server provides the relationships as resource identifiers instead of links, you can get some information about the relationships without having to load them:
person = store.from(:people).find("1")
person.hobbies
#=> [#<Lurch::Resource[Hobby] id: "1", not loaded>, ...]
person.hobbies.count
#=> 3
person.hobbies.map(&id)
#=> ["1", "2", "3"]
person.hobbies.map(&:name)
#=> Lurch::Errors::ResourceNotLoaded: Resource (Hobby) not loaded, try calling #fetch first.
person.best_friend
#=> #<Lurch::Resource[Person] id: "2", not loaded>
person.best_friend.id
#=> "2"
person.best_friend.name
#=> Lurch::Errors::ResourceNotLoaded: Resource (Person) not loaded, try calling #fetch first.Regardless of what kind of relationship it is, it can be fetched from the server:
person.best_friend.id
#=> "2"
person.best_friend.loaded?
#=> false
person.best_friend.fetch
#=> #<Lurch::Resource[Person] id: "2", name: "Alice">
person.best_friend.loaded?
#=> true
person.best_friend.name
#=> "Alice"Pagination
Lurch supports traversing and requesting paginated results if the server implements pagination:
people = store.from(:people).all
#=> #<Lurch::Collection[Person] size: 1000, pages: 100>If the server responded with meta data about the resources, you can get some information about them without loading them all:
people.size
#=> 1000
people.page_count
#=> 100NOTE: This data comes from the top-level meta key in the jsonapi response document. It assumes by default the keys are "record-count" and "page-count" respectively, but can be configured in the store.
To request a specific page, use the page query method:
people = store.from(:people).page(number: 12, size: 50).all
#=> #<Lurch::Collection[Person] size: 1000, pages: 20>If you'd like to traverse the whole set, you can do that using the collection enumerator or the page enumerator:
people.map(&:name)
# ...many HTTP requests later...
#=> ["Summer Brakus", "Katharina Orn", "Mr. Angus Hickle", "Collin Lowe PhD", "Kaylie Larson", ...]
people.each_page.map(&:size)
# ...many HTTP requests later...
#=> [10, 10, 10, 10, ...]NOTE: These enumerators can cause many HTTP requests to the server, since when it runs out of the first page of resources, it will automatically request the next page to continue.
TIP: Don't use #count on a collection to get its size. Use #size instead. #count causes the entire collection to be traversed, whereas #size will try and get the information from the collection meta data.
You can also just get the resources from the current page as an array:
people.resources
#=> [#<Lurch::Resource[Person] id: "2", name: "Summer Brakus", email: "[email protected]", twitter: "@summerb2b">, ...]Authentication
You can add an Authorization header to all your requests by configuring the store:
store = Lurch::Store.new("...", authorization: "Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOjEsIm5hbWUiOiJCb2IifQ.")Customize Faraday
You can customize faraday by passing a block to Store.new.
Use this to add arbitrary headers or faraday middlewares.
store = Lurch::Store.new("http://example.com/api") do |conn|
# conn.use MyFaradayMiddleware
conn.headers['X-Request-Id'] = '123'
end
store.from(:people).allContributing
- Fork it (https://github.com/peek-travel/lurch/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request