RESTful SNMP Over HTTP: Part III

Here's Part III of our series on how to RESTfully view the SNMP protocol. Let's see how traps can be managed following SNMP needs and HATEOS guidelines. 

Traps Management

Traps, together with InformRequest, are probably the most difficult SNMP operations to port in HTTP RESTful concepts. This is because the general HTTP behavior does not foresee connections coming from the server to the client, so the client may not be able to receive HTTP requests from the server. For this reason, the mapping of these operations is critical, and their implementation may heavily depend on needs and available resources.

The first solution (which is also the easiest) requires the simple creation of a trap resource at the uniform interface level, so create a specific URI like URI/ROOT/trap/ that identifies the ongoing notifications. The user is then able to GET such resource and to retrieve the list of modifications that are currently available, just as a GET on a tree element of the MIB outputs the list of contained objects.

At this level, it is possible to map the mere SNMP trap operation if the entity-body of the response contains the same information provided by actual SNMP traps (sysUpTime, OID, and optional variable bindings). Since then the main content of a trap is an OID, this idea describes the actual HTTP/URI mapping.

Another possibility, which less connected with the uniform interface of the ROA but is more related to the actual SNMP standard, is allowed by the HTTP 1.1 standard. Version 1.1 of HTTP allows clients to open a connection and keep it open. Through this connection, the server may send a response to the newly created trap immediately every time a trap is generated in the system.

In this situation, the single GET request to the URI/ROOT/trap/ resource remains continuously active while the operations in the network device are ongoing. The network device itself will send a part of a GET response containing data for a newly generated trap without closing the connection.

InformRequest Management

By extending the trap management described above, it is possible to implement the SNMP InformRequest the same way as the trap keeping the same /trap resource URI. Since the user must acknowledge to the system the fact that it has received the InformRequest, once the user retrieves the list of available notifications, it may use the HTTP TRACE method on the URI of a specific entry.

As specified by the standard, the TRACE method “invoke[s] a remote, application-layer loop- back of the request message.” To work in a safe and idempotent way with the trap and InformRequest resources, to inform the server that user has received such trap/InformRequest resource, and to receive a further confirmation from the server, the TRACE method is the only solution.

Let's analyze the usability of the other HTTP methods in the uniform interface perimeter. Except for the POST, they all are safe and idempotent so they would operate in the same way. Using DELETE  will render the subject trap URI (plus OID) so that it's no longer available for further users that are acting on the same network device.

The results of GET get done on the /trap/{OID} URI and shall reflect the actual /{OID} resource identified by the trap and so the response changes accordingly. Instead of “200 OK,” the response should use a “303 See Other” response code, providing the actual OID (without the /trap element) of the identified resource.

By PUTting a trap resource (PUT method with the /trap prefix and the OID) to notify the server about user’s side reception, the uniform interface requires that a value is set for such resource or the resource itself would be modified. Since PUT modifies the resource, two or more users working on the same network device may hide possibly previous modifications with their own.

The other possible solution to the TRACE method would be the non-safe and non-idempotent use of the POSTT method from HTTP protocol.

Format and Language Customizations

HTTP protocol provides two specific header fields that have to use to request for a specific output format (Accept) and a specific language (Accept-Language). They shall both be used, whether needed and meaningful, to boost the usage of the uniform interface and the HTTP itself, but a couple of customizations (both user- and software-oriented) can be added to the description above, in order to simplify software clients implementation and human user interactions when these two qualities have to be constrained. These customizations are anyway fully compatible with the uniform interface and the ROA concepts depicted above.

The first customization is the human language of the results: adding, for example, .en, .ja, .it to a URI means that agent has requested to receive the content with English, Japanese or Italian translation. So the following URI, with postponed .en: URI_ROOT/1/3/6/1/mgmt/mib/system/sysDescr.en will provide resource content in English language, whether meaningful.

The second customization is the output format of the results: adding a desired output format to a URI, gives the user the possibility to ask for a specific output solution, still using the uniform interface of RESTful and resources management. The URI scheme URI_ROOT/1/3/6/1/2/1/1/1.json will reply with a JSON-formatted content whereas the URI with XML extension (as URI_ROOT/1/3/6/1/2/1/1/1.xml) will provide XML content to the requester, and so forth.

Obviously, the HTTP header fields are to be preferred, but these two solutions may simplify software implementation and may also help human user understanding the whole request and the expected output.

It is also possible to chain these two customizations (in any order) so that URI_ROOT/1/3/6/1/2/1/1/1.en.atom will provide the content in Atom format, English language.

Transaction-Like Behavior

RESTful SNMP can use this uniform interface and HTTP functionalities to introduce transactional-like behaviors for grouping operations (multiple SNMP SETs). This resembles the SNMP possibility to use one single request with multiple and possibly unrelated PDUs in the same request — usually to SET related values in one shot, even though the associated resources are different.

To push further on the uniform interface concept, transactions themselves are to be considered resources — but, instead of associating them to OIDs, they can be system-wide published and they can be queried onto through a URI like URI_ROOT/t/. Using this URI with the HTTP POST method, the user will be able to create new transactions letting the system provide the URI on to which act directly.

Mimicking a notable example from Sam Ruby and Leonard Richardson's RESTful Web Services, a possible sequence of operations to create a transaction would be POST /t HTTP/1.1 with a response 201 Created¶Location: /t/hg42. With this sequence of request/response, the system provides the user (human or automatic, whatever) the URI associated to the newly requested and created transaction.

This will be followed by the normal usage described above, except for the fact that the URI described above will be based on the URI /t/hg42 (as per the example) instead of /.

So, continuing the example, a PUT request to the OID 1.3.6.1.2.1.118.1.2.2 (alarmActiveTable) is done with URI_ROOT/t/hg42/1/3/6/1/2/1/118/1/2/2/535135/1/1373382000000/4;5;9 and to this further sequences of GET or PUT operations, or any other sequence according to user and network device needs, may follow.

Then, as per all transactions, the user may want to commit or rollback it according to the results of the single operations. The use of an HTTP DELETE request managed the rollback of the transaction at URI provided by the system (DELETE /t/hg42 HTTP/1.1 ) and the transaction rolls back with a 200 OK response.

Instead, whether the user wants to commit such transaction, the request would be similar, simply changing the HTTP method PUT /t/hg42 HTTP/1.1 and possibly (but not necessarily) adding a simple text entity-body with, say, “commit” and the transaction will be committed.

Again, fulfilling the uniform interface, the response may contain a list of performed operations, with their URIs, so the user may have a complete set of results.

From this point on, a committed transaction will not reply to a DELETE operation or will simply reply with a "403 Forbidden" response status. Depending on the implementation the automatic deletion of the transactional resource or to, probably better, keep it for future reference. With the same uniform interface, each time a resource exists, it can also reply to a DELETE request providing the status (open/on-going or commit/rollback) and possibly the list of performed requests/operations and their results.

Conclusion

Following these mapping rules and the definitions for indexing and filtering and the uniform usage of HTTP methods, you can be able to map in an easy way almost all behaviors and operations defined by SNMP protocol. HTTPS usage provides security (as per SNMPv3) and, with proper enhancements, output formats customizations are available.

In the next (and last) part, we'll close and say goodbye — with some hints and possible ideas for usage and implementations! 

Check out the other articles here:

• RESTful SNMP Over HTTP: Part I

• RESTful SNMP Over HTTP: Part II

• RESTful SNMP Over HTTP: Part IV