LHC

LHC uses typhoeus for http communication.

See LHS, if you are searching for something more high level that can query webservices easily and provides easy data access.

Quick Start Guide

  response = LHC.get('http://datastore/v2/feedbacks')
  response.data.items[0]
  response.data.items[0].recommended
  response.body     # String
  response.headers  # Hash

Basic methods

Available are get, post, put & delete.

Other methods are available using LHC.request(options).

Formats: like json etc.

You can use any of the basic methods in combination with a format like json:

LHC.json.get(options)

Currently supported formats: json

A request from scratch

  response = LHC.request(url: 'http://local.ch', method: :options)
  response.headers

  response = LHC.request(url: 'http://datastore/v2/feedbacks', method: :get)
  response.data

→ Read more about the request object

→ Read more about the response object

Accessing data

The response data can be access with dot-notation and square-bracket notation. You can convert response data to open structs or json (if the response format is json).

  response = LHC.request(url: 'http://datastore/entry/1')
  response.data.as_open_struct #
  response.data.as_json # { name: 'local.ch' }
  response.data.name # 'local.ch'
  response.data[:name] # 'local.ch'

You can also access response data directly through the response object (with square bracket notation only):

  LHC.json.get(url: 'http://datastore/entry/1')[:name]

Parallel requests

If you pass an array of requests to LHC.request, it will perform those requests in parallel.
You will get back an array of LHC::Response objects in the same order of the passed requests.

  options = []
  options << { url: 'http://datastore/v2/feedbacks' }
  options << { url: 'http://datastore/v2/content-ads/123/feedbacks' }
  responses = LHC.request(options)

LHC.get([request1, request2, request3])
# returns [response1, response2, response3]

Follow redirects

LHC.get('http://local.ch', followlocation: true)

Transfer data through the body

Data that is transfered using the HTTP request body is transfered as you provide it.
Also consider setting the http header for content-type.

  LHC.post('http://datastore/v2/feedbacks',
    body: feedback.to_json,
    headers: { 'Content-Type' => 'application/json' }
  )

Configuration

You can configure global endpoints, placeholders and interceptors.

  LHC.configure do |c|
    c.placeholder :datastore, 'http://datastore/v2'
    c.endpoint :feedbacks, ':datastore/feedbacks', params: { has_reviews: true }
    c.interceptors = [LHC::Caching]
  end

→ Read more about configuration

URL-Templates

Instead of using concrete urls you can also use url-templates that contain placeholders.
This is especially handy for configuring an endpoint once and generate the url from the params when doing the request.

  url = 'http://datastore/v2/feedbacks/:id'
  LHC.config.endpoint(:find_feedback, url, options)
  LHC.get(:find_feedback, params:{ id: 123 })
  # GET http://datastore/v2/feedbacks/123

This also works in place without configuring an endpoint.

  LHC.get('http://datastore/v2/feedbacks/:id', params:{ id: 123 })
  # GET http://datastore/v2/feedbacks/123

If you miss to provide a parameter that is part of the url-template, it will raise an exception.

Exception handling

Anything but a response code indicating success (2**) throws an exception.

→ Read more about exceptions

Custom error handling

You can provide custom error handlers to handle errors happening during the request.

If a error handler is provided nothing is raised.

If your error handler returns anything else but nil it replaces the response body.

handler = ->{ do_something; return {name: 'unknown'} }
response = LHC.get('http://something', error_handler: handler)
response.data.name # 'unknown'

Ignore certain errors

As it’s discouraged to rescue errors and then don’t handle them (ruby styleguide),
but you often want to continue working with nil, LHC provides the ignored_errors option.

Errors listed in this option will not be raised and will leave the response.body and response.data to stay nil.

response = LHC.get('http://something', ignored_errors: [LHC::NotFound])

response.body # nil
response.data # nil
response.error_ignored? # true
response.request.error_ignored? # true

Interceptors

To monitor and manipulate the http communication done with LHC, you can define interceptors.

  class TrackingIdInterceptor < LHC::Interceptor

    def before_request(request)
      request.params[:tid] = 123
    end
  end

→ Read more about interceptors

A set of core interceptors is part of LHC,
like
Caching,
Monitoring,
Authentication,
Rollbar,
Prometheus.

→ Read more about core interceptors

License

GNU Affero General Public License Version 3.