ApiHelper Class Reference

API Helper class.
Class instance accessor: Api More...

Public Member Functions
ApiHelper	Handle (string apiCall, Func< object, object > handler)
	Defines a handler function that will be called when a web service call starting with apiCall is received. Use this to add user-defined web service API methods.
MigInterfaceCommand	Parse (object apiCall)
	Parses the given (api call) string as a MigInterfaceCommand object.
object	Call (string apiCommand, object data=null)
	Invokes an API command and gets the result.

Detailed Description

API Helper class.
Class instance accessor: Api

Member Function Documentation

Handle()

ApiHelper Handle	(	string	apiCall,
		Func< object, object >	handler
	)

Defines a handler function that will be called when a web service call starting with apiCall is received. Use this to add user-defined web service API methods.

Returns

ApiHelper

Parameters

apiCall	API call.
handler	Handler.

API methods should respect the following format:

<domain>/<address>/<command>[/<option_0>[/.../<option_n>]]

For instance, a program that control Philips Hue lights will implement API methods like this:

Api.Handle( "HomeAutomation.PhilipsHue", (args) =>
{
    var request = Api.Parse(args);
    // handle the received request
});

So an API call to set a Philips Hue light with address 3 to 50% can be done via HTTP GET

GET /api/HomeAutomation.PhilipsHue/3/Control.Level/50

or from a csharp program

var responseObject = Api.Call("HomeAutomation.PhilipsHue/3/Control.Level/50");

When this call is received by the handler, the object args passed to it must be parsed using Program.ParseApiCall method, which will return an object containing the following fields

var request = Program.ParseApiCall(args);
//  request -> {
//      Domain,         // (string)
//      Address,        // (string)
//      Command,        // (string)
//      Data,           // (object)
//      OriginalRequest // (string)
//  }

This object also provide a method request.GetOption(<index>) to get eventual options passed with this call.

Example

Api.Handle( "HomeAutomation.PhilipsHue", (args) =>
{
    var request = Api.Parse(args);
    // request.Domain          -> "HomeAutomation.PhilipsHue"
    // request.Address         -> 3
    // request.Command         -> Control.Level
    // request.GetOption(0)    -> 50
    // request.Data            -> null (not used in this case)
    // request.OriginalRequest -> "HomeAutomation.PhilipsHue/3/Control.Level/50"
    if (request.Domain == "HomeAutomation.PhilipsHue" && request.Command == "Control.Level")
    {
        var deviceAddress = request.Address;
        var deviceLevel = request.GetOption(0); // the first option has index 0
        // TODO: set dimming level of light with address 'deviceAddress' to 'dimmerLevel' %
        return new ResponseText("OK");
    }
    return new ResponseText("ERROR");
});

Parse()

MigInterfaceCommand Parse

(

object

apiCall

)

Parses the given (api call) string as a MigInterfaceCommand object.

Returns

The mig command.

Parameters

apiCall

Api Command instance (MigInterfaceCommand) or string (eg. "HomeAutomation.X10/A5/Control.Level/50").

Call()

object Call	(	string	apiCommand,
		object	data = null
	)

Invokes an API command and gets the result.

Returns

The API command response.

Parameters

apiCommand	Any MIG/APP API command without the /api/ prefix.
data	Data object. (optional)

---

The documentation for this class was generated from the following file:

• ApiHelper.cs