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 a JSON initial representation.
The Universal Messaging REST API supports three different HTTP commands. GET is used for representations of events, POST for publishing, and PUT for purging. JSON supports byte arrays and dictionary events for publishing, which map to native Universal Messaging event types. Two MIME types are available: text and application.
Configuration
After you create a REST plugin for an interface, you can select the plugin on the plugins panel for that interface and enter values 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 JSON, and what functionality each provides, as well as detailed examples of requests and responses for each command.
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.
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:
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 or dictionary event to be published to channel testchannel.
Acceptable request representations:
Available response representations:
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:
Available response representations:
JSON Representation
A JSON representation of channels/queues or events in a channel or queue as specified by the ChannelOrQueue parameter.
If the parameter points 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"
}
}
If the parameter points 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 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, if the parameter points to a non-existing container, or channel or 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
}
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.
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.
If the publish call is successful, the response code is 201 and the response looks like this:
{
"Response": "OK"
}
If the publish call fails 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
If the purge call is successful, the response code is 200 and the response looks like this:
{
"Response": "OK"
}
If the purge call fails 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 |
application/json