Define Jeckle::Resource API and DSL

[tomas-stefano]

Define Jeckle::Resource API and DSL

[brennovich]

I came across APIs that have weird namespaces/options, so, I put the concept of options, look:

http://myapi/search/simple/v1/

Here we have 3 things that can variate:

• search (Services can be distribute and require a scope, like search or workflow)
• simple (Sometimes APIs have formats specified like namespaces)
• version (APIs evolves, we need to support a easy way to support that)

(I noticed that I use that word namespace a lot, maybe we can use namespace instead options)

[brennovich]

Faraday does not parse JSON automatically only if we define middlewares to do that. So, our gem can have a interface to Faraday's middleware inclusion, where the middleware knows how to parse as the user need. Or, we can define a concept of Response Object (for now I'm solving that way).

Hopefully I'll have some time this evening to open a pull request with the Response Object concept ;)

[tomas-stefano]

Ok!

[brennovich]

Today I had a very interesting discuss with @ruisantos about the concepts involved on a API wrapping and, also, in a well defined and usage of such a library.

Basically, we agreed in two main arguments:

1. All the API definitions (base_uri, logger, etc) should not be at the Resource declaration, a Resource must be only a way to transport data that doesn't need to know how to do it.
2. A Resource can have different APIs to consume depending on an action. Example: A Order RESTful endpoints can point to a service, while the workflow actions can be in another.

We came up with the following draft:

# APIs configuration block
Jeckle::API.config do |c|
  c.register :restful do
     base_uri 'myapi.com'
     logger Rails.logger # or any other logger
     filter :password, :sensitive_data # show [FILTERED] in the logger.
     options version: 'v2'
     headers 'Content-Type' => 'application/whatever.complex.header.v2+json;charset=UTF-8'
     basic_auth username: 'chucknorris', password: 'nowThatYouKnowYouMustDie'
  end

  c.register :workflow do
     base_uri 'myapiworkflow.com'
     logger Rails.logger # or any other logger
     basic_auth username: 'chucknorris', password: 'nowThatYouKnowYouMustDie'
  end
end

# Resource definition
class MyApiResource
  include Jeckle::Resource

  attribute :id, Integer

  default_api :restful
  custom_api :workflow, only: [:cancel]

  def cancel
    @request.delete "#{id}/cancel"
  end
end

[ruianderson]

What about something like this:

class MyApiResource
  action :cancel, method: :delete, on: :member, custom_api: :workflow

  # Alternative
  custom_api :workflow do
    action :cancel, method: :delete # on: :member => # default
    action :whatever, on: :collection 
  end

  def my_own_method(id)
    resource = api.find(id)
    resource.whatever!

    workflow.cancel(id)
  end
end

In this case we don't need to implement the "actions" but just declare them inside a api and let Jeckle do the hard work!

Maybe "action" is not that good, but you got it.

[brennovich]

I liked! We can get action :cancel, method: :delete, on: :member, custom_api: :workflow for a first version and then &block alternative.

Also we can have something to aim RESTful resources:

class MyApiResource
  include Jeckle::Resource

  restful_actions api: :workflow, except: [:delete]
end

[tomas-stefano]

I liked the DSL. In the next week, I'll spend 1 hour of each day implementing this DSL. I'll create a branch in the next week and If you're interesting you can contribute too!

[tomas-stefano]

Btw, some small changes ...

Jeckle configuration will be just calling (Jeckle.configure instead Jecke::API.

   Jeckle.configure do |config|
     # ...
   end

Other thing that I want to talk is the possibility of each request the user can implement your own headers, query strings and params in the included class.

For example an API that needs to pass the credentials in the header will be something like this:

   class MyOwnResource
     include Jeckle::Resource

     def headers
       { 
         'Homers-Token'    => 'ihuuu', 
         'Homer-Animmal' => 'Spider-pig-Spider-pig',
         'Homer-App-Id'    => current_user.app_id
      }
     end
  end

Or it has the possibility to pass a block/proc to the configuration example. Wdyt?

[brennovich]

We can rely on a block/proc, for now we can stick on support only confg block header definition.

Also, I think we already have a good DSL to start, I'll document that on our wiki.

[brennovich]

https://github.com/tomas-stefano/jeckle/wiki/DSL-Definition

[brennovich]

What you guys think about we have a Trello board to help us out?

[tomas-stefano]

Ok with the Trello! =-)