Dev-Jam:RESTful Interfaces

From OpenNMS

A RESTful interface is a web service conforming to the REST architectural style as described in the book RESTful Web Services. This page is describes the work being done to develop a RESTful interface for opennms.

RESTful Interfaces

The idea here is to create RESTful interfaces to the various opennms data objects.

Steps

Upgrade to Spring 2.5 - (7/29 finished with the migration but hitting some problem starting the webapp)
Integrate Jersey with opennms - (7/30 finished this with the help of agalue... mergined to trunk)
Create a sample jersey resourse - (7/30 agalue created a simple resource at http://localhost:8980/opennms/rest/node/{nodeid} it currently only shows xml)
Work with Craig Miskell to revise the urls for the other main pieces and pick a small piece to add
Develop RESTful access to snmp-config.xml including creating DAOs etc.

Notes

Need to figure out how security will work with this... some stuff shoue be readable by anyone but writable only by some.

Process

We'll hopefully be following the process from RESTful Web Services to develop the Web Service:

Figure out the data set
Split the data set into resources

For each kind of resource

Name the resources with URLs
Expose a subset of the uniform interface
Design the representations accepted from the client
Design the representations served to the client
Integrate this resource into existing resources, using hypermedia links and forms
Consider the typical course of events: what's supposed to happen?
Consider error conditions: what might go wrong?

Data format

XML?
JSON is too JS specific IMHO; XML is parseable by every language on the planet
Or is it easy enough to do good things with the writers to produce either?

Nouns

List of nouns (objects/things/resources) that we need to expose (in no particular order, and probably incomplete):

Node
Interface
Service
Event
Notification (messages)
Alarm
Outage
Notification (configurations)
- Destination Paths
  - Targets (notification targets)
Data Collections
- Data items (OIDs, JMX attributes, HTTP collected values etc)
Thresholds
User
Group
Role
Category (whatever the hell that means)
Graph
Chart
Stored collector data (?)
Scheduled outages
DiscoveryConfig (capsd)
Rescan
Application
SNMPConfig

URLs

Standard Params

The following are standard params which are available on most resources (noted below)

limit - integer, limiting the number of results. This is particularly handy on events and notifications, where an accidental call with no limit could result in many thousands of results being returned, killing either the client or the server. If set to 0, then no limit applied
offset - integer, being the numeric offset into the result set from which results should start being returned. E.g., if there are 100 result entries, offset is 15, and limit is 10, then entries 15-24 will be returned. Used for pagination
Filtering: All properties of the entity being accessed can be specified as parameters in either the URL (for GET) or the form value (for PUT and POST). If so, the value will be used to add a filter to the result. By default, the operation is equality, unless the "comparator" parameter is sent, in which case it applies to *all* comparisons in the filter. Multiple properties will result in an "AND" operation between the filter elements. Available comparators are:
- eq Checks for equality
- ne Checks for non-equality
- ilike Case-insensitive wildcarding (% is the wildcard)
- like Case-sensitive wildcarding (% is the wildcard)
- gt Greater than
- lt Less than
- ge Greater than or equal
- le Less than or equal

If the value "null" is passed for a given property, then the obvious operation will occur (comparator will be ignored for that property).
"notnull" is handled similarly.

Ordering: If the parameter "orderBy" is specified, results will be ordered by the named property. Default is ascending, unless the "order" parameter is set to "desc" (any other value will default to ascending)

Raw where clause: If there is a "query" parameter, it will be used as a raw where clause (hibernate syntax), and added to any other filters created by other parameters

Standard filter examples

Take /events as an example.

/events?eventUei=uei.opennms.org/internal/rtc/subscribe

would return the first 10 events with the rtc subscribe UEI, (10 being the default limit for events)

/events?eventUei=uei.opennms.org/internal/rtc/subscribe&limit=0

would return *all* the rtc subscribe events (potentially quite a few)

/events?id=100&comparator=gt

would return the first 10 events with an id greater than 100

/events?eventAckTime=notnull

would return the first 10 events that have a non-null Ack time (i.e. those that have been acknowledged)

/events?eventAckTime=notnull&id=100&comparator=gt&limit=20

would return the first 20 events that have a non-null Ack time and an id greater than 100. Note that the notnull value causes the comparator to be ignored for eventAckTime

/events?eventAckTime=2008-07-28T04:41:30.530+12:00&id=100&comparator=gt&limit=20

would return the first 20 events that have were acknowledged after 28th July 2008 at 4:41am (+12:00), and an id greater than 100. Note that the same comparator applies to both property comparisons.

/events?orderBy=id&order=desc

would return the 10 latest events inserted (probably, unless you've been messing with the id's)

Nodes

GET each of these Suggestions (plenty to start with, more to follow once the below is done and we've got a handle on how these work)

/nodes (all nodes) default offset = 0 limit = 25 && limit=0 to get all
/nodes/count?nodeLabel="xyz"&offset=10&limit=10
/nodes?nodeLabel="xyz" (clarify exactly how that works)
/nodes/{id} (specific node)
/nodes/{id}/ipinterfaces (all interfaces for node)
/nodes/{id}/ipinterfaces/{ipaddr} (specific interface)
/nodes/{id}/ipinterfaces/{ipAddr}/services (all services on interface)
/nodes/{id}/ipinterfaces/{ipAddr}/services/{service} (specific service)
/nodes/{id}/snmpinterfaces (all snmp services)
/nodes/{id}/snmpinterfaces/{ifIndex} (particular snmp interface)
/nodes/{id}/categories
/nodes/{id}/categories/{categoryName}

POST to a 'list' URL adds an element to the list (eg post a node to /nodes)
PUT to a singleton URL to udpate the data for that element (for example PUT data to /nodes/3)

POST requires an XML using application/xml as a ContextType
PUT requires a Form Data using application-form/urlencoded as a ContextType

DELETE to a singleton URL to delete the element

Uses standard params (see above). Default limit is 10

Events

/events - Returns all events that match the specified filter (if any) (see standard params).
/events/count - Returns a bare (plain text) integer with the count of events that match the specified filter (if any)
/events/{id} - Returns just the specified event (equivalent to /events?id={id}, but prettier)

PUT operates on both /events and /events/{id}. It takes a single "ack" parameter which if set to "true" causes the event to be acknowledged (by the authenticated user accessing the service). Any other value causes the notification to be unacknowledged. When PUTting to /events, all events which match the provided filter parameters will be touched
POST to /events 'sends the event to the system' (NOT IMPLEMENTED YET, but is intended)
DELETE is not supported

Uses standard params (see above). Default limit is 10

Notifications

/notifications - Returns all notifications that match the specified filter (if any) (see standard params).
/notifications/count - Returns a bare (plain text) integer with the count of notifications that match the specified filter (if any)
/notifications/{id} - Returns just the specified notification (equivalent to /notifications?id={id}, but prettier)

PUT takes a single "ack" parameter. If set to "true", the notification is acknowledged (by the authenticated user accessing the service). Any other value (that parses as a boolean) causes the notification to be unacknowledged
PUT currently only works on /notifications/{id}
POST/DELETE are not supported

Uses standard params (see above). Default limit is 10

Alarms

/alarms - Returns all alarms that match the specified filter (if any) (see standard params).
/alarms/count - Returns a bare (plain text) integer with the count of alarms that match the specified filter (if any)
/alarms/{id} - Returns just the specified alarm (equivalent to /alarms?id={id}, but prettier)

PUT operates on both /alarms and /alarms/{id}. It takes a single "ack" parameter which if set to "true" causes the event to be acknowledged (by the authenticated user accessing the service). Any other value causes the notification to be unacknowledged. When PUTting to /alarms, all alarms which match the provided filter parameters will be touched POST/DELETE are not supported

Uses standard params (see above). Default limit is 10

Outages

/outages - Returns all outages that match the specified filter (if any) (see standard params).
/outages/count - Returns a bare (plain text) integer with the count of outages that match the specified filter (if any)
/outages/{id} - Returns just the specified outage (equivalent to /outages?id={id}, but prettier)

Read-Only - only GET supported
Uses standard params (see above). Default limit is 10

Graphs

NOT YET IMPLEMENTED

/graph/{graphTemplate}/{resourceId}?startTime={startTime}&endTime={endTime}
/nodes/{id}/reports/{reportTemplateName}
/report/{reportTemplate}/{resourceId}?startTime={startTime}&endTime={endTime}
/nodes/{id}/{ipaddr}/reports/{reportTemplateName}

These are readonly

Admin

NOT YET IMPLEMENTED

/admin/config/graphTemplates
/admin/config/graphTemplates/{graphTemplateName}

normal RESTful behaviour

/admin/config/reportTemplates
/admin/config/reportTemplates/{reportTemplateName}

normal RESTful behavior

Config stuff should be under a separate tree, e.g.:

/admin/config/notification
/admin/config/notification/{name}

Hmmmm, interesting choice:

/admin/config/notification/destpath/{name} OR
/admin/config/destpath/{name}

destpaths are notification related, but are not sub-resources of notifications. What's correct?

/admin/config/users/{name}
/admin/config/group
/admin/config/group/{name}
/admin/config/role
/admin/config/role/{name}
/admin/config/thresholdgroup
/admin/config/thresholdgroup/{groupname}
/admin/config/thresholdgroup/{groupname}/{id} ID is a composite of data source, value, rearm and type (high/low/relative/whatever), colon separated
/admin/config/snmp (Default level config)
/admin/config/snmp/definition/????? How to identify the individual definitions? Query for those that match some attributes? I think this needs a synthetic id (GUID or incrementing number)

Operations: