REST Plugin

REST Plugin

The REST plugin allows access to the Universal Messaging REST API, and can be enabled on any HTTP or HTTPS (NHP or NHPS) interface. The Universal Messaging REST API is designed for publishing, purging and representing events published on channels and queues in 2 initial representations: JSON and XML.

The Universal Messaging REST API supports three different HTTP commands. GET is used for representations of events, POST for publishing and PUT for purging. Both XML and JSON support byte arrays, XML and Dictionary events for publishing, which map to native Universal Messaging event types. There are two MIME types available: text and application.

Configuration

Once you have created the REST plugin on the interface you require it on, you can then select it from the plugins panel for that interface and enter values as desired for the configuration parameters.

Parameter Name	Description	Default Value
AddUserAsCookie	Add the username to the session's cookies.	Blank
AuthParameters	A list of key=value strings, which are passed to the Authenticator's init() function.	Blank
Authenticator	Classname of Authenticator to use. If blank, no authentication is used.	Blank
EnableStatus	Enables Realm status details. Default is disabled, for security reasons.	False
GroupNames	A comma separated list of groups. The user must be a member of at least one in order to be granted access.	Blank
IncludeTypeInfo	Includes type information for event dictionaries.	False
NamespaceRoot	Name of the namespace folder to be used as root.	Blank
ReloadUserFileDynamically	If set to true and authentication is enabled, fAuthenticator.reload() is called on each request.	True
RoleNames	A comma-separated list of names. The user must have at least one to gain access.	Blank
Security Realm	Name of the authentication realm.	Blank
SessionTimeout	Time in seconds to time-out inactive http sessions.	300

The REST plugin supports WADL documentation which is accessible through the HTTP OPTIONS command. Once you have completed setting up your REST plugin, you can verify it works by opening a browser to the NHP interface in the mount URL path, and appending the query string ?method=options. For example, for an NHP interface running on port 9000 on localhost, and having the plugin mounted on "/rest", open a browser to http://localhost:9000/rest/API?method=options.

Following this will display an HTML version of the full Universal Messaging REST API documentation which is generated by applying an XSL processor to the WADL XML document. The XML document itself can be obtained by accessing the plugin URL without the ?method=options query string. For example, the curl command line tool can be used as follows:

curl -XOPTIONS http://localhost:9000/rest/API

What follows is a summary of the three HTTP commands for both XML and JSON, and what functionality each provides, as well as detailed examples of requests and responses for each command.

XML: GET

Provides XML representations of channels/queues or events in a channel or queue as specified by the ChannelOrQueue parameter. The parameter is represented by the URI Path following the REST Plugin mount.

If the value supplied corresponds to a Universal Messaging namespace container, the representation returned is a list of channels and queues present in the container. If the value supplied corresponds to a channel or queue then the representation returned is a list of events. Finally if the value supplied does not correspond to either a container or a channel / queue a 404 response will be returned with no body.

Available response representations:

text/xml

application/xml

XML: POST

Allows publishing of an event to a channel or queue specified by the ChannelOrQueue parameter, which is represented by the URI Path following the REST Plugin mount. For example http://localhost:9000/rest/API/xml/testchannel expects an XML byte, XML or dictionary event to be published to channel testchannel.

Acceptable request representations:

text/xml

application/xml

Available response representations:

text/xml

application/xml

XML: PUT

Allows purging of 1 or more events already published on a channel or queue specified by the ChannelOrQueue parameter, which is represented by the URI Path following the REST Plugin mount. For example http://localhost:9000/rest/API/xml/testchannel expects a request to purge events to be published to channel testchannel. Purging can be specified by EID and selector.

Acceptable request representations:

text/xml

application/xml

Available response representations:

text/xml

application/xml

JSON: GET

Provides JSON representations of channels/queues or events in a channel or queue as specified by the ChannelOrQueue parameter. The parameter is represented by the URI Path following the REST Plugin mount.

Available response representations:

application/json

JSON: POST

Allows publishing of an event to a channel or queue specified by the ChannelOrQueue parameter, which is represented by the URI Path following the REST Plugin mount. For example http://localhost:9000/rest/API/json/testchannel expects a JSON byte, XML or dictionary event to be published to channel testchannel.

Acceptable request representations:

application/json

Available response representations:

application/json

JSON: PUT

Allows purging of 1 or more events already published on a channel or queue specified by the ChannelOrQueue parameter, which is represented by the URI Path following the REST Plugin mount. For example http://localhost:9000/rest/API/json/testchannel expects a request to purge events to be published to channel testchannel. Purging can be specified by EID and selector.

Acceptable request representations:

application/json

Available response representations:

application/json

Representation: XML

XML REPRESENTATION : An XML representation of channels/queues or events in a channel or queue as specified by the ChannelOrQueue parameter.

Should the parameter point to an existing container, the response code is 200 and the response looks like this:

<Nirvana-RealmServer-ChannelList NumberOfChannels="2">

<Channel EventsConsumed="0" EventsPublished="0" LastEventID="-1"
Name="testqueue" NumberEvents="0"
fqn="http://localhost:8080/rest/API/xml/testqueue"/>
<Channel EventsConsumed="0" EventsPublished="2" LastEventID="223"
Name="testchannel" NumberEvents="2"
fqn="http://shogun:8080/rest/API/xml/testchannel"/>
</Nirvana-RealmServer-ChannelList>

If the REST plugin is configured to include realm status, some additional information about the realm is presented:

Should the parameter point to an existing channel or queue, the response code is 200 and the response looks like this:

<Nirvana-RealmServer-EventList>

<Details ChannelName="http://localhost:8080/rest/API/xml/testsrc"
FirstEvent=
"http://localhost:8080/rest/API/xml/testsrc?Data=Dictionary&EID=first"
LastEID="223"
LastEvent=
"http://localhost:8080/rest/API/xml/testsrc?Data=Dictionary&EID=last"
NextLink="http://localhost:8080/rest/API/xml/testsrc?EID=224" StartEID="222"/>
<Event ByteLink="http://localhost:8080/rest/API/xml/testsrc?Data=Byte&EID=222"
DataSize="9" EID="222" Tag="Test Tag" hasByte="true"/>
<Event
DictionaryLink=
"http://localhost:8080/rest/API/xml/testsrc?Data=Dictionary&EID=223"
EID="223" hasDictionary="true"/>
</Nirvana-RealmServer-EventList>

You can follow the provided links to view individual events. If you choose to look at an individual byte event, the response code is 200 and the response looks like this:

<Nirvana-RealmServer-RawData>

<EventData ChannelName="http://localhost:8080/rest/API/xml/testsrc" EID="222">
<Data>
<![CDATA[VGVzdCBCb2R5]]>
</Data>
<Tag>
<![CDATA[Test Tag]]>
</Tag>
</EventData>
</Nirvana-RealmServer-RawData>

If you choose to look at an individual XML event, the response code is 200 and the response looks like this:

<Nirvana-RealmServer-XMLData>

<EventData ChannelName="http://localhost:8080/rest/API/xml/testsrc" EID="222"
isDOM="true">
<Data>
<myUserDataTag>
Some User Data
</myUserDataTag>
</Data>
<Tag>
<![CDATA[Test Tag]]>
</Tag>
</EventData>
</Nirvana-RealmServer-XMLData>

If you choose to look at an individual Dictionary event, the response code is 200 and the response looks like this:

If the rest plugin is configured to include type information in representations, dictionary event representations will include them. In this case, responses looks like this:

Finally, should the parameter point to a non existing container or channel / queue, the response code is 404 without a response body

XML PUBLISH REQUEST

XML Byte events can be represented as follows:

Important:
data and tag should always be submitted in base64 encoded form.

XML DOM events can be represented as follows:

Important:
data and tag should always be submitted in base64 encoded form.

XML Dictionary events can be represented as follows:

Optionally, dictionary events can include type information (see Types). This allows the Universal Messaging REST API to preserve these types when publishing the event. The types are defined as byte constants to keep typed dictionary events compact in size.

XML Dictionary events (with type information) can be represented as follows:

Important:
byte[ ] types should always be submitted in base64 encoded form.

XML PUBLISH RESPONSE : A XML representation to indicate the status of attempting to publish an event to the channel or queue specified by the ChannelOrQueue parameter.

Should the publish call be successful, the response code is 201 and the response looks like this:

<Nirvana-RealmServer-PublishRequest>
<response value="ok"/>
</Nirvana-RealmServer-PublishRequest>

Should the publish call fail for any reason, the response code is 400 and the response looks like this:

<Nirvana-RealmServer-Error>
<response value="failInput"/>
<errorcode value="ErrorCode"/>
<errormessage value="Error Message"/>
</Nirvana-RealmServer-Error>

XML PURGE REQUEST : A XML representation of a Purge Request that indicates the event(s) to purge.

A XML purge request looks as follows:

<Nirvana-RealmServer-PurgeRequest startEID="10" endEID="20" purgeJoins="false">
<selector>
<![CDATA[]]>
</selector>
</Nirvana-RealmServer-PurgeRequest>

XML PURGE RESPONSE : A XML representation to indicate the status of attempting to purge an event to the channel or queue specified by the ChannelOrQueue parameter.

Should the purge call be successful, the response code is 200 and the response looks like this:

<Nirvana-RealmServer-PurgeRequest>
<response value="ok"/>
</Nirvana-RealmServer-PurgeRequest>

Should the purge call fail for any reason, the response code is 400 and the response looks like this:

<Nirvana-RealmServer-Error>
<response value="failInput"/>
<errorcode value="ErrorCode"/>
<errormessage value="Error Message"/>
</Nirvana-RealmServer-Error>

Representation: JSON

JSON REPRESENTATION : A JSON representation of channels/queues or events in a channel or queue as specified by the ChannelOrQueue parameter.

Should the parameter point to an existing container, the response code is 200 and the response looks like this:

{
"Channels":
[ {
"EventsConsumed": "0",
"EventsPublished": "0",
"LastEventID": "-1",
"Name": "testqueue",
"NumberEvents": "0",
"fqn": "http://localhost:8080/rest/API/json/testqueue"
}, {
"EventsConsumed": "0",
"EventsPublished": "0",
"LastEventID": "212",
"Name": "testchannel",
"NumberEvents": "0",
"fqn": "http://localhost:8080/rest/API/json/testchannel"
} ],
"Comment": "Constructed by my-channels Nirvana REST-Plugin :
Wed Mar 02 11:38:30 EET 2011",
"Name":
"Nirvana-RealmServer-ChannelList",
"NumberOfChannels": "2",
}

If the REST plugin is configured to include realm status, some additional information about the realm is presented:

{
"Channels":
[ {
"EventsConsumed": "0",
"EventsPublished": "0",
"LastEventID": "-1",
"Name": "testqueue",
"NumberEvents": "0",
"fqn": "http://localhost:8080/rest/API/json/testqueue"
}, {
"EventsConsumed": "0",
"EventsPublished": "0",
"LastEventID": "212",
"Name": "testchannel",
"NumberEvents": "0",
"fqn": "http://localhost:8080/rest/API/json/testchannel"
} ],
"Comment": "Constructed by my-channels Nirvana REST-Plugin :
Wed Mar 02 11:38:30 EET 2011",
"Name": "Nirvana-RealmServer-ChannelList",
"NumberOfChannels": "2",
"Realm": {
"FreeMemory": "503291048",
"RealmName": "nirvana6",
"Threads": "104",
"TotalConnections": "1",
"TotalConsumed": "0",
"TotalMemory": "530186240",
"TotalPublished": "0"
}
}

Should the parameter point to an existing channel or queue, the response code is 200 and the response looks like this:

{
"ChannelName": "http://localhost:8080/rest/API/json/testsrc",
"Comment": "Constructed by my-channels Nirvana REST-Plugin : Wed
Mar 02 12:19:22 EET 2011",
"Events":
[ {
"ByteLink": "http://localhost:8080/rest/API/json/testsrc?Data=Byte&EID=213",
"DataSize": "9",
"EID": "213",
"Tag": "Test Tag",
"hasByte": "true"
}, {
"DictionaryLink":
"http://localhost:8080/rest/API/json/testsrc?Data=Dictionary&EID=214",
"EID": "214",
"hasDictionary": "true"
} ],
"FirstEvent": "http://localhost:8080/rest/API/json/testsrc?Data=Dictionary&EID=first",
"LastEID": "214",
"LastEvent": "http://localhost:8080/rest/API/json/testsrc?Data=Dictionary&EID=last",
"Name": "Nirvana-RealmServer-EventList",
"NextLink": "http://localhost:8080/rest/API/json/testsrc?EID=215",
"StartEID": "213"
}

You can follow the provided links to view individual events. If you choose to look at an individual byte event, the response code is 200 and the response looks like this:

{
"ChannelName": "http://localhost:8080/rest/API/json/testsrc",
"Comment": "Constructed by my-channels Nirvana REST-Plugin :
Wed Mar 02 12:21:46 EET 2011",
"Data": "VGVzdCBCb2R5",
"EID": "213",
"Name": "Nirvana-RealmServer-RawData",
"Tag": "Test Tag"
}

If you choose to look at an individual XML event, the response code is 200 and the response looks like this:

If you choose to look at an individual Dictionary event, the response code is 200 and the response looks like this:

{
"dictionary":
{
"testboolean": [true],
"testcharacter": ["a"],
"testdictionary": [
{
"testboolean": [true],
"testcharacter": ["a"],
"testdouble": [1],
"testfloat": [1],
"testinteger": [1],
"testlong": [1],
"teststring": ["teststringvalue"]
}],
"testdouble": [1],
"testfloat": [1],
"testinteger": [1],
"testlong": [1],
"teststring": ["teststringvalue"],
"teststringarray": [[
"one",
"two",
"three"
]]
},
"isPersistent": true
}

If the rest plugin is configured to include type information in representations, dictionary event representations will include them. In this case, responses looks like this:

{
"dictionary":
{
"testboolean": [ true, 3 ],
"testcharacter": [ "a", 6 ],
"testdictionary":
[ {
"testboolean": [ true, 3 ],
"testcharacter": [ "a", 6 ],
"testdouble": [ 1, 2 ],
"testfloat": [ 1, 5 ],
"testinteger": [ 1, 4 ],
"testlong": [ 1, 1 ],
"teststring": [ "teststringvalue", 0 ]
}, 9 ],
"testdouble": [ 1, 2 ],
"testfloat": [ 1, 5 ],
"testinteger": [ 1, 4 ],
"testlong": [ 1, 1 ],
"teststring": [ "teststringvalue", 0 ],
"teststringarray":
[[
"one",
"two",
"three"
], 100, 0 ]
},
"isPersistent": true
}

Finally, should the parameter point to a non existing container or channel / queue, the response code is 404 without a response body

JSON PUBLISH REQUEST

JSON Byte events can be represented as follows:

{
"data": "VGVzdCBCb2R5",
"isPersistent": true,
"tag": "VGVzdCBUYWc="
}

Important:
data and tag should always be submitted in base64 encoded form.

JSON DOM events can be represented as follows:

{
"data": "VGVzdCBCb2R5",
"isDOM": true,
"isPersistent": true,
"tag": "VGVzdCBUYWc="
}

Important:
data and tag should always be submitted in base64 encoded form.

JSON Dictionary events can be represented as follows:

{
"dictionary":
{
"testboolean": [true],
"testcharacter": ["a"],
"testdictionary":
[{
"testboolean": [true],
"testcharacter": ["a"],
"testdouble": [1],
"testfloat": [1],
"testinteger": [1],
"testlong": [1],
"teststring": ["teststringvalue"]
}],
"testdouble": [1],
"testfloat": [1],
"testinteger": [1],
"testlong": [1],
"teststring": ["teststringvalue"],
"teststringarray":
[[
"one",
"two",
"three"
]]
},
"isPersistent": true
}

Dictionary events (with type information) can be represented as follows:

{
"dictionary":
{
"testboolean": [ true, 3 ],
"testcharacter": [ "a", 6 ],
"testdictionary":
[ {
"testboolean": [ true, 3 ],
"testcharacter": [ "a", 6 ],
"testdouble": [ 1, 2 ],
"testfloat": [ 1, 5 ],
"testinteger": [ 1, 4 ],
"testlong": [ 1, 1 ],
"teststring": [ "teststringvalue", 0 ]
}, 9 ],
"testdouble": [ 1, 2 ],
"testfloat": [ 1, 5 ],
"testinteger": [ 1, 4 ],
"testlong": [ 1, 1 ],
"teststring": [ "teststringvalue", 0 ],
"teststringarray":
[ [
"one",
"two",
"three"
], 100, 0 ]
},
"isPersistent": true
}

Important:
byte[] types should always be submitted in base64 encoded form.

JSON PUBLISH RESPONSE : A JSON representation to indicate the status of attempting to publish an event to the channel or queue specified by the ChannelOrQueue parameter.

Should the publish call be successful, the response code is 201 and the response looks like this:

{
"Response": "OK"
}

Should the publish call fail for any reason, the response code is 400 and the response looks like this:

{
"errorcode": "ErrorCode",
"errormessage": "Error Message",
"response": "failInput"
}

JSON PURGE REQUEST : A JSON representation of a Purge Request that indicates the event(s) to purge.

A JSON purge request looks as follows:

{
"endEID": 20,
"purgeJoins": false,
"selector": "",
"startEID": 10
}

JSON PURGE RESPONSE : A JSON representation to indicate the status of attempting to purge an event to the channel or queue specified by the ChannelOrQueue parameter

Should the purge call be successful, the response code is 200 and the response looks like this:

{
"Response": "OK"
}

Should the purge call fail for any reason, the response code is 400 and the response looks like this:

{
"errorcode": "ErrorCode",
"errormessage": "Error Message",
"response": "failInput"
}

Types

Type	ID
String	0
Long	1
Double	2
Boolean	3
Integer	4
Float	5
Character	6
Byte	7
Short	8
Dictionary	9
Array	100