REST Lua Agent

Introduction

The RestLuaAgent is an asynchronous helper for Lua scripts running within the LogicApp. It is used for sending out REST client requests.

• The REST Client Agent may be used by any Lua script, regardless of which Service initiated that script.
• For receiving REST server requests you need to use the RestLuaService Service.

The RestLuaAgent communicates with one or more instances of the RestClientApp which can be used to communicate with one or more external REST servers.

The RestLuaAgent communicates with the RestClientApp using the REST-C-… messages.

• The RestLuaAgent is tied to the rest action key.
• The REST-C-SENT message is written to the debug trace log, but not available to the Lua script.

Configuring RestLuaAgent

The RestLuaAgent is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <parameters>
            ...
            <parameter name="default_rest_app_name" value="REST-CLIENT"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="RestClientApp::RestLuaAgent" libs="../apps/rest/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

In addition, the RestLuaAgent must be configured with the name of the RestClientApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

Invoking RestLuaAgent

A Lua Script can access the RestLuaAgent rest action with code such as the following:

    local n2svcd = require "n2.n2svcd"
    local rest_client_api = require "n2.n2svcd.rest_client"

    local handler = function (soap_args)
        local response = rest_client_api.request (nil, {
            host = 'www.nsquared.nz',
            path = '/cgi-bin/search.cgi',
            query = { section = 'FAQ', subsection = 'site' }
        })
        if (response.code ~= 200) then
            error ("Failed to access search page.")
        end
        if (not response.content) then
            error ("Search page returned no content.")
        end

        return { NUM_BYTES = str.length (response.content) }
    end

    return n2svcd.handler (handler)

This is standard Lua-style library usage. The n2/n2svcd/rest_client.lua library is loaded with require "n2.n2svcd.rest_client". Then methods are invoked on the returned library object.

This example passes nil as the rest endpoint identifier. This routes the rest request to the default configured RestClientApp name. If more than one rest endpoint is present, then the first parameter is the “route”, or rest endpoint key.

The RestLuaAgent API

All methods may raise a Lua Error in the case of exception, including:

• Invalid input parameters supplied by Lua script.
• Unexpected results structure returned from RestClientApp.
• Processing error occurred at RestClientApp.
• Timeout occurred at RestClientApp.

.request

The request method accepts an request object parameter with the following attributes.

The request method returns an response object with the following attributes.

[Fragment] Example REST client request:

    local response = rest_client_api.request (nil, {
        host = 'www.nsquared.nz',
        path = '/cgi-bin/search.cgi',
        query = 'FAQ'
    })
    if (response.code ~= 200) then
        error ("Failed to access search page.")
    end
    if (not response.content) then
        error ("Search page returned no content.")
    end