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 #<OpenStruct name='local.ch'>
  response.data.as_json # { name: 'local.ch' }
  response.data.name # 'local.ch'
  response.data[:name] # 'local.ch'

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.

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

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 = [CacheInterceptor]
  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'

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

License

GNU Affero General Public License Version 3.