Ruby Integration

Ruby can easily be used to make RESTful api requests using Net::HTTP and Net::HTTPS; both part of the Ruby standard library.

You will need to ensure the following dependencies are defined within your code:

require "addressable/uri"
require 'net/http'
require 'rubygems'

# You may need to install the json library using "gem install json"
require 'json'

Making a GET Request

This example uses the the API to load the name associated with an email address, the ApiConnection class is used for code simplification.

# Define the fields required for the rest request
data = {
   'api_id' => 'cDSJwf6hECIjy_3XgoGv7q8PsgI.',
   'api_key' => '3Mu6rpQY6n0IQDUYVG5SyFRtIA1uOf3gpOuAdk9Uaa4.',
   'email_address' => 'example@demo.com'
}

# Create an instance of the wrapper class   
api = ApiConnection.new

# Make the API request 
results = api.request('GET', 'https://control.instiller.co.uk/rest/users/details', data)

# Check for a valid result
if results['valid'] == false
    # Your error handling code
    if results['http_code'] == false
        # Problem connecting to the API
        puts "Connection error"
    else
        # Show why we failed to load the details
        puts "Error: " + (results['response']['code'] || "") + " - " + (results['response']['reason'] || "")
    end
else
    # Your User processing code
    user = results['response'];
    puts "Your contacts name is: " + (user['first_name'] || "")  + " " + (user['last_name'] || "")
end

Making a POST Request

This example uses the the API to add or update a User and capture the unique ID allocated by the system, the ApiConnection class is used for code simplification.

# Define the fields required for the rest request
data = {
   'api_id' => 'cDSJwf6hECIjy_3XgoGv7q8PsgI.',
   'api_key' => '3Mu6rpQY6n0IQDUYVG5SyFRtIA1uOf3gpOuAdk9Uaa4.',
   'email_address' => 'example@demo.com',
   'reference_code' => 'MY-CUSTOMER-REF'
}

# Create an instance of the wrapper class   
api = ApiConnection.new

# Make the API request 
results = api.request('POST', 'https://control.instiller.co.uk/rest/users/add_or_update', data)

# Check for a valid result
if results['valid'] == false
    # Your error handling code
    if results['http_code'] == false
        # Problem connecting to the API
        puts "Connection error"
    else
        # Show why we failed to load the details
        puts "Error: " + (results['response']['code'] || "") + " - " + (results['response']['reason'] || "")
    end
else
    # Your User processing code
    user = results['response'];
    puts "Your User has been created or updated our ID is: " + (user['user_id'].to_s || "")
end

ApiConnection Class

The following class will handle connecting to the API and sending both GET and POST requests.

class ApiConnection
    def request(method, url, data = false, response_type = 'application/json')

        # Initialise the response
        results = {'valid' => false}

        # For get requests add the parameters to the request
        if method == 'GET' 
            # Check to see if we need to sort out the query string 
            if data != false
                # Use the addressable object
                uri = Addressable::URI.new
                uri.query_values = data
                url = url + "?" + uri.query
            end
        end 

        # Parse the url to create the request connection
        uri = URI.parse(url); 

        # Use exception handling to catch connection errors
        begin

            # Work out what method we are requesting
            if method == 'GET' 
                # Create the request and use a secure connecion
                request = Net::HTTP.new(uri.host, uri.port)
                request.use_ssl = true 

                # Run the API request
                response = request.get(uri.request_uri) 
                results['http_code'] =  response.code;
            else 
                # Create a post request
                request = Net::HTTP::Post.new(uri.request_uri)
                request.set_form_data(data)

                # Create the HTTP class to send the request securely
                https = Net::HTTP.new(uri.hostname, uri.port)
                https.use_ssl = true 

                # Run the HTTPS post
                response = https.request(request)
                results['http_code'] =  response.code;
            end

            # Work out if we need to decode the json 
            if response_type == 'application/json'
                results['response'] = JSON.parse(response.body)
            else
                results['response'] = response.body 
            end

            # Check the response code all valid requests return a 200 
            if results['http_code'] == "200"
                results['valid'] = true;
            end
        rescue
            # Connection failed
            results['http_code'] = false
            results['error'] = 'Failed to send API request'
        end

        # Result the results of the request
        return results
    end
end

What Next?

This example code can be customised to access any API endpoint:

• Locate the API endpoint you require using the API explorer
• Change the URL used to request the API
• Change the fields used in the request to match the API documentation