Skip to content
A tiny api client toolkit for ruby that supports only JSON content-type. ( Curb/JSON wrapper )
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.gitignore
.rubocop.yml
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
tp_client.gemspec

README.md

TINYclient, a tiny HTTP/JSON crud client toolkit

Gem Version Build Status Code Climate

TINYclient is inspired by Active Record and based on Curb.

Setup

  • Be sure that Curb/Curl works properly on your machine.
  • install the gem
gem install tiny_client

Getting Started

Configuration

You can initialize your API by extending the TinyClient::Configuration

class MyConf < TinyClient::Configuration

  def initialize
    @url = 'http://localhost:3000/api/1.0'
    @headers = { 'Authorization' => 'token asdfasf4ffsafasdf@12rfsdfa' }
    @limit = 100
    @connect_timeout = 30 # seconds
  end
end

You can use that configuration in your resource.

class Author < TinyClient::Resource
  conf MyConf.instance

  path 'authors' # query will be made on http://localhost:3000/api/1.0/authors

  fields :id, :name # your resource attributes

  nested Books # your resource nested resource
end

class Book < TinyClient::Resource
  conf MyConf.instance
  path 'books'
  fields :id, :title
end

Usage

Now you will be able to this:

author = Author.show(1) # Get /authors/1.json
author.name = 'P. K. D.'
author.save!   # PUT /authors/1.json { "author" : { "name" : "Bob" } }

book = Book.new
book.title = 'Confessions of a crap artist'
book = author.add_book(book) # POST /authors/1/books.json { "book" : { "title" : ".." }

book.id.present? # true

books = Book.index(limit: 10) # GET /books.json?limit=10

ed = Author.new
ed.name = 'Poe'
ed.save! # POST /authors.json { "author" : { "name" : "Poe" } }
ed.id.present?

ed_books = ed.books(limit: 10) # GET /authors/{ed.id}/books.json
first = ed_books.first
first.load! # GET /books/{first.id}.json
first.name.present?

# You can also navigate through all resources

Author.index_all do |author| # It will retrieve all the authors, using limit, and offset query params to paginate
 # Do something for each author
end


Author.index_in_batches(limit: 1000) do |authors|
  # retrieve authors by batch of 1000
end

Instance methods behavior

load!

It will perform a get request on the resource id and set the resource fields value to the value retrived by the response.

author.load! # GET /authors/{author.id}.json ->  { id: 1, name: 'Toto' ... }
author.name # 'Toto'

save!

It will create the resource if id is not set, otherwise it will update it. The resource fields value will be updated by the response body content.

toto = MyModule::Author.new
toto.save! # POST /authors.json { author: {} }

toto.id # should have been set by through the reponse

toto.name = 'Toto'
toto.save! # PUT {author: {name: 'Toto'}} -> /authors/{toto.id}.json

Only changed values will be passed through the body content.

You can clear changes with #clear_changes! You can now which fields has been marked has changed with #changes

Changes is automatically clear when you perform a request ( i.e call, #show #index #get #put #post save! and so on)

Nested resource

You can add a nested resource thanks to the nested class methods.

class Author < TinyClient::Resource
  nested Books, Magazines
end

It will allows you to call your nested resource directly from an instance of your parent resource.

author = Author.show(1)
author.books(limit: 100)  # index GET /authors/1/books.json?limit=100
book = author.book(1)     # show  GET/authors/1/books/1.json
book.title = 'New title'
author.update_book(book)  # update  PUT /authors/1/books/1.json -- { 'book': { 'title': 'New title' } }
author.remove_book(book)  # destroy DELETE /authors/1/books/1.json
author.add_book(book)     # create  POST /author/1/books.json -- { 'book': { 'title': 'New title' } }
author.books_all.each     # x GET /authors/1/books.json?limit=.. -- Enumerator -- Retrieve ALL books using limit and offset to handle pagination

This is equivalent to the following:

author = Author.show(1)
author.nested_index(Book, limit: 100)
book = author.nested_show(Book, 1)
book.title = 'New title'
author.nested_update(book)
author.nested_delete(book)
author.nested_create(book)
author.nested_all(Book, limit: 10) # retrieve all books, quering the server by batch of 10;

Constraint & Support

JSON only

TinyClient supports only JSON data. Accept: application/json header is set.

POST/PUT create/update

The content passed to the server will always be prefixed by the class name in lower case.

toto = MyModule::Author.new
toto.save! # POST { author: {} }

Pagination / Buffer

Pagination, buffer is achieve through limit and offset params.

Author.index_all({limit: 100}) # Will queries the server by batch of 100, until all authors has been retrieved through the enumerator.

Content-Encoding support

TinyClient support gzip Content-Encoding. Response with gzip Content-Encoding will be automatically decompressed. You can set the Accept-Encoding: gzip through the configuration headers.

Development

You can run the test using:

rake
You can’t perform that action at this time.