Eezee

Eezee sounds like "Easy"

The easiest HTTP client for Ruby!

With Eezee you can do these things:

• Define external services in an initializer file and use them through a simple method
• Take HTTP requests just extending a module and call the HTTP request method in your class/module
• Set before and after hooks to handle your requests, responses, and errors
• Handle all requests, responses, and errors in the same way
• Log the request, response, and errors
• Set general request timeout and open connection timeout
• Raise errors in failed requests
• Spend more time coding your API integrations instead defining and testing HTTP settings and clients

This gem is supported for Ruby 2.6+ applications.

• Getting started
  • Installation
  • Supported HTTP Methods
  • How to take a request
  • Request options
    • Available Request options
  • Services
    • How a service works
  • Request
  • Response
  • Errors
  • Examples
    • Complete integrations
    • Hooks
• The why to use Eezee instead Faraday
• Contributing
• License

Add this line to your application's Gemfile:

gem 'eezee'

If you're on Rails you can run this line below to create the initializer:

rails generate eezee:install

Eezee supports these HTTP methods:

• GET
• POST
• PATCH
• PUT
• DELETE

And here are the corresponding Eezee's HTTP methods:

• get(request_options)
• post(request_options)
• patch(request_options)
• put(request_options)
• delete(request_options)

OBS: The param request_options is optional.

To take a request using any of these methods you just have to call the HTTP method, and if you want, you can pass the options.

module RickMorty::Resource::Character
  extend Eezee::Client

  def self.index
    get(url: 'rickandmortyapi.com/api', protocol: :https, path: 'character')
  end

  def self.find(id)
    get(
      url: 'rickandmortyapi.com/api',
      protocol: :https,
      path: 'character/:character_id',
      params: { character_id: id }
    )
  end

  def self.create(payload)
    post(
      url: 'rickandmortyapi.com/api',
      protocol: :https,
      path: 'character',
      payload: payload
    )
  end

  def self.update(id, payload)
    post(
      url: 'rickandmortyapi.com/api',
      protocol: :https,
      path: 'character/:character_id',
      params: { character_id: id }
      payload: payload
    )
  end

  def self.destroy(id)
    delete(
      url: 'rickandmortyapi.com/api',
      protocol: :https,
      path: 'character/:character_id',
      params: { character_id: id }
    )
  end

Request options are the request settings. They can be used to define services, request options and as a param when you take the HTTP request. For example:

module RickMorty::Resource::Character
  extend Eezee::Client

  eezee_request_options protocol: :https,
                        url: 'rickandmortyapi.com/api'
                        path: 'character/:character_id'

  def self.index
    get
  end

  def self.find(id)
    get(params: { character_id: id })
  end

  def self.update(id, payload)
    put(
      params: { character_id: id },
      payload: payload,
      after: ->(_req, res) { do_something!(res) }
    )
  end
end

The method eezee_request_options can receive all of Available Request options.

When the HTTP methods were called, Eezee has created a Request setting with the options defined in the module and merge with the options passed as a param in the HTTP methods.

Here are the list of available options and about them:

It's common your app has integrations with many external services and this gem has a feature to organize in one file the settings of these external service integrations and it provides an easy way to get these settings.

For example, I will integrate with Rick and Morty Api using a service:

• I'll declare it in an initializer file:

Eezee.configure do |config|
  config.add_service :rick_morty_api,
                     protocol: :https,
                     url: 'rickandmortyapi.com/api'
end

• In my resource, I'll catch the service and pass other settings:

module RickMorty::Resource::Character
  extend Eezee::Client

  eezee_service :rick_morty_api
  eezee_request_options path: 'character/:character_id'

  def self.index
    get
  end

  def self.find(id)
    get(params: { character_id: id })
  end
end

When Ruby loads a class/module and it has the method eezee_service declared with a service's name, by default, Eezee will try load the service and create a request base for the class/module, so, when the class/module takes a request, Eezee will create the final request instance based on request base to take the HTTP request. You can turn it lazy setting the option lazy: true, therefore, the final request will be created just in the HTTP request. If the service doesn't exist when Eezee search about it, it will be raised the error Eezee::Client::UnknownServiceError.

About the method add_service, you can pass all of Available Request options. The meaning of this part is to organize in one way the external services integrations.

In Hooks, you always receive the param request and it is an instance of Eezee::Request. Available Request options are the accessors of Eezee::Request, just call for the name, like:

request.protocol
# => :https

request.url
# => "rickandmortyapi.com/api"

In Hooks and the return of the request you have an instance of Eezee::Response. This class can be used for successful and failed requests. Here are all methods you can call from a response:

Eezee can raise errors in some situations:

• When the specified service is unknown
• When the request got a timeout
• When the request got a failure response

• Eezee::Client::UnknownServiceError

• Eezee::TimeoutError

Important: This case happens just if the request option raise_error is true.

• Eezee::RequestError for all errors (ancestor of all below)
• Eezee::BadRequestError for code equals 400
• Eezee::UnauthorizedError for code equals 401
• Eezee::ForbiddenError for code equals 403
• Eezee::ResourceNotFoundError for code equals 404
• Eezee::UnprocessableEntityError for code equals 422
• Eezee::ClientError for code between 400 and 499
• Eezee::InternalServerError for code equals 500
• Eezee::ServiceUnavailableError for code equals 503
• Eezee::ServerError for code between 500 and 599

All of Eezee::RequestError has the accessor @response with an instace of Eezee::Response.

Important: This case happens just if the request option raise_error is true.

Here are some examples:

• Integrating with JsonPlaceHolder API and Go Rest API - With Service and Request options
• Integrating with JsonPlaceHolder API and Go Rest API - With Request options
• Integrating with JsonPlaceHolder API and Go Rest API - Without Services and Request Options

• Adding a header into the request using before hook
• Handling resource not found errors using after hook

So, it's an important part of this README. This gem uses Faraday as the HTTP client and Faraday is an excellent HTTP client, but it brings many difficult, or, in other words, many things could be easier, like:

• If you work with microservices, you'll create a Faraday Connection setting per ms, or, it's so common to see many Faraday Connection setting in the same project.
• To raise errors with Faraday you know to set an adapter (it could be easier)
• When we have a successful response or an error, the way to catch the params (code, body) is completely different
• Faraday doesn't have any way to set the external services in an initializer, you'll have to create yours
• At least, it's common in projects the people create files to instantiate Faraday Connection but these people don't test these files

All of these things and others are contemplated by Eezee!

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The gem is available as open source under the terms of the MIT License.