Format

Default encoding format from response body returned by Jarvis to the client.

Specify json, json.array, json.rest, xml, csv, or xlsx.

• This may be over-ridden a per-request basis with the CGI parameter format.
• This parameter is entirely separate from the encoding of the submitted POST data in the request, which is specified via the content-type header in the HTTP request.

JSON Format

Consider the Demo application supplied with Jarvis. This application uses the json format. The following chapter will describe the definition of datasets and the use of parameters. For now we consider only the structure of the returned content.

http://localhost/jarvis-agent/demo/boat_class

The JSON format response for a data fetch is wrapped in an outer object.

• The returned tuples are contained in an array with object key “data”.
• Each tuple is represented as an object. Missing fields are omitted.

Response is:

{
   "data" : [
      {
         "active"      : "Y",
         "class"       : "Makkleson",
         "id"          : "6",
         "description" : "Suitable for infants and those of timid heart."
      },
      {
         "active"      : "N",
         "class"       : "X Class",
         "id"          : "4",
         "description" : "Product of a deranged mind."
      }
   ],
   "fetched"      : 2,
   "returned"     : 2,
   "error_string" : "",
   "logged_in"    : 1,
   "group_list"   : "admin",
   "username"     : "admin"
}

Top level attributes are:

JSON Array Format

The JSON Array format response for a data fetch is wrapped in an outer object.

• The returned tuples are contained in an array with object key data.
• Each tuple is represented as an array.
• The column names are given separately.
• The order of the array elements for each tuple matches the given column order.
• Empty elements in the array are given as as JSON null value.

Consider the following request:

http://localhost/jarvis-agent/demo/boat_class?format=json.array

Response is:

{
   "data" : [
      [
         "Y",
         "Makkleson",
         "Suitable for infants and those of timid heart.",
         1
      ],
      [
         "N",
         "X Class",
         "Product of a deranged mind.",
         2
      ]
   ],
   "logged_in"  : 1,
   "group_list" : "admin",
   "username"   : "admin",
   "returned"   : 2,
   "columns"    : [
      "active",
      "class",
      "description",
      "id"
   ],
   "fetched"      : 2,
   "error_string" : ""
}

JSON Rest Format

The JSON Rest format is a simplified version of the default json format which returns purely the data component. This is suitable for pure REST-ful frameworks which do not expect any metadata.

• The data value is returned a top-level array.
• All of the other attributes are discard.

Consider the following request:

http://localhost/jarvis-agent/demo/boat_class?format=json.rest

Response is:

"data" : [
   {
      "active"      : "Y",
      "class"       : "Makkleson",
      "id"          : "6",
      "description" : "Suitable for infants and those of timid heart."
   },
   {
      "active"      : "N",
      "class"       : "X Class",
      "id"          : "4",
      "description" : "Product of a deranged mind."
   }
]

XML Format

The XML format response for a data fetch is wrapped in an outer object.

• The returned tuples are contained in a data element.
• Each tuple is represented as a row element.
• Fields are specified as attributes of the row element.

Consider the following request:

http://localhost/jarvis-agent/demo/boat_class?format=xml

The returned content in XML is:

<?xml version="1.0" encoding="iso-8859-1" ?>
<?meta name="GENERATOR" content="XML::Smart/1.6.9 Perl/5.010000 [linux]" ?>
<response logged_in="1" username="admin" error_string="" group_list="admin" fetched="2" returned="2">
    <data>
        <row active="Y" class="Makkleson" description="Suitable for infants and those of timid heart." id="6"/>
        <row active="N" class="X Class"   description="Product of a deranged mind."                    id="4"/>
    </data>
</response>

CSV Format

The CSV format response for a data fetch is standard CSV encoding with a header row.

• The header row gives column names.
• Fields are separated by commas.
• Strings containing spaces or special characters are in double quotes.
• Multi-line strings are supported, a newline character is used.

Consider the following request:

http://localhost/jarvis-agent/demo/boat_class?format=csv

The returned content in CSV format is:

active,class,description,id
Y,Makkleson,"Suitable for infants and those of timid heart.",1
N,"X Class","Product of a deranged mind.",2

XLSX Format

The response is identical in structure to the CSV format. However, it is encoded in XLSX format, used by Microsoft Excel 2000 and later.