NetMRI API Protocol
- Shirly Tsang
The underlying protocol used for the NetMRI API is HTTP /1.1, which is described in RFC2616, http://www.w3.org/Protocols/rfc2616/rfc2616.html.
This section provides more information about the API builds on top of HTTP to allow access and control of NetMRI. For purposes of this document, HTTP and HTTPS are the same. That is, the interface supports both HTTP and HTTPS URL schemes; whether on a plain or SSL socket, the API will work in the same manner.
This section is especially relevant if you intend to access the Core API directly; it is not necessary for users of the Perl API to understand all the details here.
Authentication
When your script connects to NetMRI, it must pass the URL, username, and password to the client object. The URL and credentials can be passed into the constructor when connecting to NetMRI.
The following is a cURL example of how to authorize a NetMRI appliance to make requests:
curl -u "admin:yourpassword" http://netmri_host_name_or_ip/api/server_info.json
or
curl -u "admin:yourpassword" http://netmri_host_name_or_ip/api/server_info.xml
Request Format
The HTTP standard requires the requests to consist of a request line, headers, and an optional request body. The NetMRI does not utilize any special request methods or headers beyond the HTTP/1.1 standard.
For POST operations, the client must send a request body in addition to the request line and headers. NetMRI supports several different request body content-types: application/x-www-form-urlencoded, multipart/form-data, application/json, application/xml. Most calls will accept any of these formats as equivalent. However, certain calls may specify that they accept only a subset of these content types.
Content Types: application/x-www-form-urlencoded and multipart/form-data
The application/x-www-form-urlencoded and multipart/form-data content types can be described as form encodings and are commonly used by browsers to POST form data.
The application/x-www-form-urlencoded content type is the default content-type that browsers use when POSTing a form and is defined in the HTML specification. It encodes the parameters in the same manner as a GET request but places them in the request body rather than the request line. This allows much more data to be sent with the request than in a GET but is still not sufficient for file uploads.
The multipart/form-data content type fills this gap by encoding data in a way that allows more complex data types. It is defined in RFC 2388 (http://tools.ietf.org/html/rfc2388), but most user-agent libraries will support it natively.
Content Types: application/json and application/xml
The application/json content-type refers to the JavaScript Object Notation (JSON), as described in RFC 4627 (http://tools.ietf.org/html/rfc4627). The application/xml content-type, or the now deprecated text/xml content-type, is used to identify Extensible Markup Language (XML) in the request body. NetMRI supports XML 1.0 as defined in the W3C standard (http://www.w3.org/TR/2008/REC-xml-20081126/).
| JSON | XML | |
|---|---|---|
| Format | {<name>: <value><repeat as necessary, delimited bycommas>} | <?xml version="1.0"encoding="UTF-8"?><request><name>value</name>Repeat as necessary</request> |
| Example | {id: 45,"user_name": "jsmith","first_name": "John","last_name": "Smith"} | <?xml version="1.0"encoding="UTF-8"?><request><id>45</id><user_name>jsmith</user_name><first_name>John</first_name><last_name>Smith</last_name></request> |
Unless otherwise defined by the specific API call documentation, JSON requests should consist of an anonymous hash of name/value pairs, whereas XML requests should consist of a request root element with child elements representing the name/value parameter pairs.
Some API calls use more complex JSON or XML input formats. Some functionality of these calls are only accessible through a POST with one of these content types, rather than the form encodings.
Response Format
The HTTP 1.1 standard dictates that the responses consist of a status line, headers, and a response body. In addition, the NetMRI API has standardized response bodies for some of the specific status codes that may be returned.
Status Codes
The NetMRI API utilizes standard HTTP 1.1 status codes as defined in RFC2616, Section 6. One additional standard code, 102 Processing from RFC2518, is also used.
One non-standard code, 265 Deprecated, is used to indicate that the API call used is a deprecated call. This should be treated as a 200 OK with regard to processing but provides a warning that the call may go away in a future release.
The status codes below are commonly used by NetMRI. Other codes may be returned based on standard HTTP semantics.
| 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.
Standard Body by Status
In addition to the basic Content-Type, certain status codes have a standard payload or body format. This allows a higher degree of code reuse and simplified handling of the various data types within NetMRI.
102 Processing: The standard payload for this status indicates the progress of the processing, if available. If unavailable (i.e., how much processing has been completed is unknown), the “total” field will not be present, and the “done” field may or may not be present. Specific calls may add an additional payload.
| Description | JSON | XML |
|---|---|---|
| Format | {"total": <total toprocess>,"done": <done so far>} | <?xml version="1.0" encoding="UTF-8"?><response><total>total to process</total><done>done so far</done></response> |
| Example (Known) | {"total": 50123,"done": 10456} | <?xml version="1.0" encoding="UTF-8"?><response><total>50123</total><done>10456</done></response> |
| Example (Unknown) | {"done": 134} | <?xml version="1.0" encoding="UTF-8"?><response><done>134</done></response> |
| Example (Unknown) | {} | <?xml version="1.0" encoding="UTF-8"?><response/> |
200 OK: The standard payload is nothing for this status code. Many API calls will return a payload specific to the call.
201 Created: The standard payload for this status is the model and ID of the newly created entity, along with a URI to retrieve the details of the entity and the actual newly created entity. In addition, the URI will be in the Location: HTTP header. Specific calls may add an additional payload.
| JSON | XML | |
|---|---|---|
| Format | {"model": "<model name>","id": <id value>,"uri":http://<ip>/<plural-model-name>/<id>,"<model name>": { … }} | <?xml version="1.0" encoding="UTF-8"?><response><model>model name</model><id>id value</id><uri>http://<ip>/<plural-model-name>/<id>.xml</uri><model name> … </model name></response> |
| Example | {"model": "script","id": 45,"uri":"http://10.1.1.1/scripts/45""script": { "id":45, … }} | <?xml version="1.0" encoding="UTF-8"?><response><model>script</model><id>45</id><uri>http://10.1.1.1/scripts/45.xml</uri><script><id type="int">45</id>...</script></response> |
202 Accepted: The standard payload for this status is the same as for the 201 Created, except without the actual model data; it is the model and ID of the newly created entity, along with a URI to retrieve the details of the entity. The difference is that for a 201 Created code, the entity has already been created. For a 202 Accepted, the entity is in the process of being created. Thus, a request to the provided URL may return a 102 Processing instead of a 200 OK.
Just as with the 201 Created, the URI will be in the Location: HTTP header.
Specific calls may add an additional payload.
| JSON | XML | |
|---|---|---|
| Format | {"model": "<model name>","id": <id value>,"uri":"http://<ip>/<plural-model-name>/<id>"} | <?xml version="1.0" encoding="UTF-8"?><response><model>model name</model><id>id value</id><uri>http://<ip>/<plural-model-name>/<id>.xml</uri></response> |
| Example | {"model": "script","id": 45,"uri":"http://10.1.1.1/scripts/45"} | <?xml version="1.0" encoding="UTF-8"?><response><model>script</model><id>45</id><uri>http://10.1.1.1/scripts/45.xml</uri></response> |
301 Moved Permanently: No payload is present for this status code. The Location: header will indicate the redirect location. Typically used for a deprecated method that has a direct replacement.
400 Bad Request: The standard payload for this status code is an error code and message. The message may change based upon localization, therefore automated clients should use the error code. This basic format is called the error response format and is used for other 4xx status messages as well. See the following section, Standard Error Codes for details on the widely-used error responses.
| JSON | XML | |
|---|---|---|
| Format | {"error": "<error code>","message": "<errormessage>"} | <?xml version="1.0" encoding="UTF-8"?><response><error>error code</error><message>error message</message></response> |
| Example | {"error":"general/resource-in-use",message: "The requestedshared resource iscurrently in use. Pleasetry your request again ina few minutes."} | <?xml version="1.0" encoding="UTF-8"?><response><error>general/resource-in-use</error><message>The requested shared resourceis currently in use. Please try yourrequest again in a fewmintues.</message></response> |
The specific error codes returned will depend upon the API call, but certain error codes have pre-defined formats, as described below.
403 Forbidden: The standard payload is the error response format, with one of the following two error codes: “security/access-denied” or “security/authentication-required”.
404 Not Found: No standard payload is present for this status code, although some specific calls may define one.
409 Conflict: The standard payload is the error response format, which will include information on how to resolve the conflict.
410 Gone: This status code indicates that the API call requested is no longer available. A standard error/message payload may be present explaining the reason and providing direction for implementing the same functionality with the newer API.
413 Request Entity Too Large: The standard payload is the error response format, which will include details of what aspect of the request was too large (size or length of time, for example).