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.