The API provides resource data in JSON (.json), XML (.xml) or CSV (.csv) data formats. The API sets the HTTP response code and content type according to the requested format and the success or failure of the query. The default format is JSON when none is indicated in the query. The API sets the HTTP content-disposition header with a filename of query.xml (or .json or .csv). Use the filename= option to specify a different name.
Response Envelope
The API sets five fields at the top level of the response.
| success | true or false |
|---|---|
| start_row | Set according to the request. |
| num_rows | The number of rows in the current response. |
| total_rows | The number of available rows for paged queries. |
| msg | An array containing the results of the query or an error string |
JSON
The resources in the msg array contain nested hashes with the associated resources from the include= parameter.
XML
The top level of the XML response document is an XML Response entity with success, id, start_row, num_rows and total_rows attributes. The resources are contained in an XML entity named as the plural of the requested model. The XML entities representing the query results contain nested XML entities with the associated resources from the include= parameter. Underscores in association and field names are replaced by hyphens (-) .
CSV
The CSV response format does not contain paging information (numrows, totalrows). The first row of the CSV response will be the column names. It does not contain a byte-order-mark. Use of the CSV format implies the tabular option. By default all columns of the model at the start of the query are displayed. Generally the CSV format does not work with the include= parameter; use criteria= (rma::criteria) and tabular= instead. The csv format cannot be use with queries that end in a service call.