...
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.
...
| 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).