SmoothOperator

Ruby gem, that mimics the ActiveRecord behaviour but through external API's. It's a lightweight and flexible alternative to ActiveResource, that responds to a REST API like you expect it too.

Be sure to check out this micro-services example: https://github.com/goncalvesjoao/micro-services-example

Where a Rails4 app lists/creates/edits and destroys blog posts from a Padrino (aka Sinatra) app, using SmoothOperator::Rails instead of ActiveRecord::Base classes.

This micro-services example will also feature other cool stuff like:

• parallel requests;
• using HTTP PATCH verb for saving instead of PUT;
• form errors with simple_form gem;
• nested objects using cocoon gem;
• endless-pagination with kaminari gem
• and others...

---

1) Installation

Add this line to your application's Gemfile:

gem 'smooth_operator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install smooth_operator

---

2) Usage and Examples

class MyBlogResource < SmoothOperator::Base

  # HTTP BASIC AUTH
  options endpoint_user: 'admin',
          endpoint_pass: 'admin',
          endpoint: 'http://myblog.com/api/v0'

  # OR
  # smooth_operator_options
end

class Post < MyBlogResource
end

---

2.1) Creating a .new 'Post' and #save it

post = Post.new(body: 'my first post', author: 'John Doe')

post.new_record?     # true
post.persisted?     # false
post.body           # 'my first post'
post.author         # 'John Doe'
post.something_else # will raise NoMethodError

save_result = post.save # will make a http POST call to 'http://myblog.com/api/v0/posts'
                        # with `{ post: { body: 'my first post', author: 'John Doe' } }`

post.last_remote_call # will contain a SmoothOperator::RemoteCall instance containing relevant information about the save remote call.

# If the server response is positive (http code between 200 and 299):
save_result       # true
post.new_record?  # false
post.persisted?   # true
# server response contains { id: 1 } on its body
post.id # 1

# If the server response is negative (http code between 400 and 499):
save_result       # false
post.new_record?  # true
post.persisted?   # false
# server response contains { errors: { body: ['must be less then 10 letters'] } }
post.errors.body # Array

# If the server response is an error (http code between 500 and 599), or the connection was broke:
save_result       # nil
post.new_record?  # true
post.persisted?   # false
# server response contains { errors: { body: ['must be less then 10 letters'] } }
post.errors # will raise NoMethodError

  # In the positive and negative server response comes with a json,
  # e.g. { id: 1 }, post will reflect that new data
  post.id # 1

  # In case of error and the server response contains a json,
  # e.g. { id: 1 }, post will NOT reflect that data
  post.id # raise NoMethodError

---

2.2) Editing an existing record

post = Post.find(2)

post.body = 'editing my second page'

post.save

---

2.3) Customize #save 'url', 'params' and 'options'

post = Post.new(id: 2, body: 'editing my second page')

post.new_record? # false
post.persisted?  # true

post.save("save_and_add_to_list", { admin: true, post: { author: 'Agent Smith', list_id: 1 } }, { timeout: 1 })
# Will make a PUT to 'http://myblog.com/api/v0/posts/2/save_and_add_to_list'
# with { admin: true, post: { body: 'editing my second page', list_id: 1 } }
# and will only wait 1sec for the server to respond.

post.save('/#{post.id}/save_and_add_to_list')
# Will make a PUT to 'http://myblog.com/api/v0/posts/2/save_and_add_to_list'

post.save('/save_and_add_to_list')
# Will make a PUT to 'http://myblog.com/api/v0/posts/save_and_add_to_list'

---

2.4) Saving using HTTP Patch verb

class Page < MyBlogResource
  options update_http_verb: 'patch'
  # OR
  #smooth_operator_options update_http_verb: 'patch'
end

page = Page.find(2)

page.body = 'editing my second page'

page.save # will make a http PATCH call to 'http://myblog.com/api/v0/pages/2'
          # with `{ page: { body: 'editing my second page' } }`

---

2.5) Retrieving remote objects - 'index' REST action

remote_call = Page.find(:all) # Will make a GET call to 'http://myblog.com/api/v0/pages'
                              # and will return a SmoothOperator::RemoteCall instance

pages = remote_call.data

# If the server response is positive (http code between 200 and 299, or 304):
  remote_call.ok? # true
  remote_call.not_processed? # false
  remote_call.error? # false
  remote_call.status # true
  pages = remote_call.data # array of Page instances
  remote_call.http_status # server_response code

# If the server response is unprocessed entity (http code 422):
  remote_call.ok? # false
  remote_call.not_processed? # true
  remote_call.error? # false
  remote_call.status # false
  remote_call.http_status # server_response code

# If the server response is client error (http code between 400..499, except 422):
  remote_call.ok? # false
  remote_call.not_processed? # false
  remote_call.error? # true
  remote_call.status # nil
  remote_call.http_status # server_response code

# If the server response is server error (http code between 500 and 599), or the connection broke:
  remote_call.ok? # false
  remote_call.not_processed? # false
  remote_call.error? # true
  remote_call.status # nil
  remote_call.http_status # server_response code or 0 if connection broke

---

2.6) Retrieving remote objects - 'show' REST action

remote_call = Page.find(2) # Will make a GET call to 'http://myblog.com/api/v0/pages/2'
                           # and will return a SmoothOperator::RemoteCall instance

service_down = remote_call.error?

page = remote_call.data

---

2.7) Retrieving remote objects - custom query

remote_call = Page.find('my_pages', { q: body_contains: 'link' }, { endpoint_user: 'admin', endpoint_pass: 'new_password' })
# will make a GET call to 'http://myblog.com/api/v0/pages/my_pages?q={body_contains="link"}'
# and will change the HTTP BASIC AUTH credentials to user: 'admin' and pass: 'new_password' for this connection only.

@service_down = remote_call.error?

# If the server json response is an Array [{ id: 1 }, { id: 2 }]
  @pages = remote.data # will return an array with 2 Page's instances
  @pages[0].id # 1
  @pages[1].id # 2

# If the server json response is a Hash { id: 3 }
  @page = remote.data # will return a single Page instance
  @page.id # 3

# If the server json response is Hash with a key called 'pages' { current_page: 1, total_pages: 3, limit_value: 10, pages: [{ id: 4 }, { id: 5 }] }
  @pages = remote.data # will return a single ArrayWithMetaData instance, that will allow you to access to both the Page's instances array and the metadata.

  # @pages is now a valid object to work with kaminari
  @pages.total_pages # 3
  @pages.current_page # 1
  @pages.limit_value # 10

  @pages[0].id # 4
  @pages[1].id # 5

2.8) Keeping your session alive - custom HTTP Headers

Controllers ApplicationController

Models SmoothResource

class SmoothResource < SmoothOperator::Rails

  options headers: :custom_headers

  def self.custom_headers
    {
      cookie: current_user.blog_cookie,
      "X_CSRF_TOKEN" => current_user.blog_auth_token
    }
  end

  protected ############## PROTECTED #################

  def self.current_user
    User.current_user
  end

end

---

3) Methods

---

3.1) Persistence methods

Methods	Behaviour	Arguments	Return
.create	Generates a new instance of the class with *attributes and calls #save with the rest of its arguments	Hash attributes = nil, String relative_path = nil, Hash data = {}, Hash options = {}	Class instance
#new_record?	Returns @new_record if defined, else populates it with true if #id is present or false if blank.	-	Boolean
#destroyed?	Returns @destroyed if defined, else populates it with false.	-	Boolean
#persisted?	Returns true if both #new_record? and #destroyed? return false, else returns false.	-	Boolean
#save	if #new_record? makes a HTTP POST, else a PUT call. If !#new_record? and relative_path is blank, sets relative_path = id.to_s. If the server POST response is positive, sets @new_record = false. See 4.2) for more behaviour info.	String relative_path = nil, Hash data = {}, Hash options = {}	Boolean or Nil
#save!	Executes the same behaviour as #save, but will raise RecordNotSaved if the returning value is not true	String relative_path = nil, Hash data = {}, Hash options = {}	Boolean or Nil
#destroy	Does nothing if !persisted? else makes a HTTP DELETE call. If server response it positive, sets @destroyed = true. If relative_path is blank, sets relative_path = id.to_s. See 4.2) for more behaviour info.	String relative_path = nil, Hash data = {}, Hash options = {}	Boolean or Nil

---

3.2) Finder methods

Methods	Behaviour	Arguments	Return
.find	If relative_path == :all, sets relative_path = ''. Makes a Get call and initiates Class objects with the server's response data. See 4.3) and 4.4) for more behaviour info.	String relative_path, Hash data = {}, Hash options = {}	Class instance, Array of Class instances or an ArrayWithMetaData instance

---

3.3) Operator methods

...

---

3.3) Remote call methods

...

---

4) Behaviours

---

4.1) Delegation behaviour

...

---

4.2) Persistent operator behaviour

...

---

4.3) Operator behaviour

...

---

4.4) Remote call behaviour

...

---

4) TODO

1. Finish "Methods" and "Behaviours" documentation;
2. ModelSchema specs;
3. Cache.