...
| Code | Reason Phrase | Description |
|---|---|---|
| 102 | Processing | The code indicates that the server has received and is processing the request, but there is no response yet. |
| 200 | OK | The request succeeded. Standard HTTP 1.1 status code. |
| 201 | Created | The request to create an entity succeeded. Standard HTTP 1.1 status code. |
| 202 | Accepted | The request has been accepted for processing, but the processing has not been completed. Standard HTTP 1.1 status code. |
| 265 | Deprecated | The request succeeded and does not need to be repeated. However, the specified API call is deprecated and will be removed in a future version. |
| 301 | Moved Permanently | The requested resource is assigned a new permanent URI. Standard HTTP 1.1 status code. |
| 400 | Bad Request | Used for application-level error responses. For example, this will be used when a form submission fails to pass the form validations. |
| 403 | Forbidden | The server understood the request but is refusing to fulfill it. Standard HTTP 1.1 status code, but the NetMRI adds a payload to determine if this is due to access controls or lack of authentication (see below). |
| 404 | Not Found | The server has not found anything matching the Request-URI. Standard HTTP 1.1 status code. |
| 409 | Conflict | The server cannot process the request due to a conflict. This generally means that any attempt to create a new resource violates a uniqueness constraint. |
| 410 | Gone | The requested resource is no longer available at the server and no forwarding address is known. Standard HTTP 1.1 status code, used when a subsequent version obsoletes an API call. |
| 413 | Request Entity Too Large | The server is refusing to process a request because the request entity is larger than the server is willing or able to process. This is a standard HTTP 1.1 status code and is returned, for example, instead of a 102 if the request has exceeded internal NetMRI timeouts. |
Headers
The NetMRI API does not use any specialized HTTP headers.
Body
For the majority of API calls, the response body can be returned as either JavaScript Object Notation (JSON, content-type application/json), or Extensible Markup Language (XML, content-type application/xml). Some calls can optionally return JSON with special added attributes for use with the NetMRI ExtJS application (application/extjs). A few calls, such as those used to download files, will specify a particular response content type; those are documented in the specific API call documentation.
In general, the choice of response format is up to the client. The details are in the table below, but the essential rules here are:
- GET requests return application/json by default, or you may specify the format by appending .json, .xml, or .extjs to the URI.
- POST requests return the content type you posted in your request unless that was a standard HTTP form encoding. In that case, the response format will be application/json, unless you specify the .xml or .extjs extension.
The table below enumerates the various combinations of request methods, extensions, and formats, and the resulting response format.
| Request Method | Request URI Extension | Request Body Content-Type | Response Body Content-Type |
|---|---|---|---|
| GET | N/A | application/json | |
| GET | .json | N/A | application/json |
| GET | .xml | N/A | application/xml |
| GET | .extjs | N/A | application/extjs |
| POST | application/x-www-form-urlencoded | application/json | |
| POST | multipart/form-data | application/json | |
| POST | application/json | application/json | |
| POST | application/xml | application/xml | |
| POST | text/xml | application/xml | |
| POST | .json | Any supported type | application/json |
| POST | .xml | Any supported type | application/xml |
| POST | .extjs | Any supported type | application/extjs |
For application/json, the entire body of the response is an anonymous hash of name/value pairs, unless otherwise defined in the specific API call documentation. Responses using application/extjs will be the same, but will include some additional information in some cases.
For application/xml, the root element will always be the “response” element, with the children being elements tagged by the name and containing the values, unless otherwise defined in the specific API call’s documentation.
In addition, with application/xml, special handling is required to support anonymous values for the basic JSON primitive types of Number, String, Boolean, Array, Object (hash) and null. To handle this, anonymous values are tagged with “item”. Below are some example responses.
| Description | JSON | XML |
|---|---|---|
| Response with a single return parameter named “foo” with value “bar”. | {"foo": "bar"} | <?xml version="1.0" encoding="UTF-8"?><response><foo>bar</foo></response> |
| Response with a single return parameter named “foo” with integer value 123. | {"foo": 123} | <?xml version="1.0" encoding="UTF-8"?><response><foo type="array"><item type="integer">123</item><item>bar</item><item type="bool">true</item></foo></response> |
| Response with a single return parameter named foo with a hash value containing a floating-point number, a string, and a null. |
| <?xml version="1.0" encoding="UTF-8"?><response><foo type="hash"><one type="float">12.3</one><two>bar</two><three nil="true"/></foo></response> |
| Response with two named parameters, the first “foo” with a string value “bar”, the second “foofoo” with a null value. | {"foo": "bar","foofoo": null} | <?xml version="1.0" encoding="UTF-8"?><response><foo>bar</foo><foofoo nil="true"/></response> |
Common compound data types, including hashes and arrays, have a specified XML format, as shown in the examples above. These are used for generic hashes and arrays, not for well-defined objects such as a “Device”, which will be described in the specific API call.
Results Paging
Some API calls that return large result sets are limited to 1000 records per request to prevent unreasonable memory consumption on the NetMRI appliance. In this case, the response will include paging information, as in this example:
<response><total type="int">1452</total><start type="int">0</start><limit type="int">1000</start><current type="int">1000</start><devices type="array"><device>…</device> [ repeated 999 more times ]</devices></response>
where:
total specifies the total number of records available for the data type.
current specifies the number of records returned in this group. No more than 1000 records are returned at one time.
start specifies the number of the first record in this group.
limit specifies the maximum number of records that were requested.
These API calls must be repeatedly queried while modifying an input parameter to indicate which “page” to obtain. The Perl API provides this functionality without the script author needing to implement it specifically.
API calls that utilize results paging denote this in their documentation.