Output and input formats

Out API supports multiple formats for retrieving and sending data. The desired format is either defined using an filename extension within the URL, or by using the appropriate mime type within the HTTP Accept header.

Some of the formats accept additional query parameters.

All formats accept the fields= parameter that will limit the result to the given comma-separated list of field names (and, in case of the CSV format, is mandatory and defines the order).

JSON (default)

  • Extension: .json
  • Mime types: application/json, text/json, application/javascript, application/x-javascript, text/javascript
  • Query parameters: none

Example:

$ curl -o- -u ':KEY' 'https://rds.rasch.de/v2/articles/stock.json?item=440898,204803&qty=1000'
[ {
  "id" : "440898",
  "stock" : 839,
  "date" : null
}, {
  "id" : "204803",
  "stock" : 1000,
  "date" : null
} ]

XML

  • Extension: .xml
  • Mime type: text/xml
  • Query parameters: xmlTransform

Example:

$ curl -o- -u ':KEY' 'https://rds.rasch.de/v2/articles/stock.xml?item=440898,204803&qty=1000'
<?xml version="1.0" encoding="UTF-8"?>
<items><item>
  <id>440898</id>
  <stock>839</stock>
  <date/>
</item><item>
  <id>204803</id>
  <stock>1000</stock>
  <date/>
</item></items>

The xmlTransform parameter can be used to convert the output into another XML based format using a predefined XSLT template.

CSV

  • Extension: .csv
  • Mime type: text/csv
  • Query parameters: * csvSeparator: Column delimiter (default: ";", character)

    • csvDelimiter: Column delimiter (default: ";", character)
    • csvSeparator: Deprecated alias for csvDelimiter
    • csvNewline: Line delimiter (default: "\n", string)
    • csvQuote: Quote character (default: '"', character)
    • csvHeader: Print header (true) or not (false). On POST requests, this field may contain a comma-separated list of fieldnames that defines the column order in the uploaded data.
    • linewrap: See description below
    • xls: Microsoft Excel compatibility mode

This format is limited to lists of one-dimensional entries. When parsing output generated by this API be aware that multiline strings will lead to a newline within quotes. This means that the number of lines can be greater than the number of records if the output include string columns.

Newlines within columns will be encoded as quoted linelines. This means a data row containing a line wrap will be two lines in the generated CSV value. Some programs cannot parse this, e.g. PHP's fgetcsv() and Microsoft Excel. Please use the global parameter linewrap to define a replacement string for these cases.

If you want to open the file in Microsoft Excel please append xls=1 to the service URL. This enables a Microsoft Excel compatibility mode where the file is preceeded by a special sequence ("UTF-8-BOM"), columns are delimited by semi-colon and lines are delimited with CRLF instead of a simple LF.

Important:

When using CSV output format the definition of the fields= parameter is mandatory! If you really want all fields in a random order use an asterix as value (fields=*).

Examples:

$ curl -o- -u ':KEY' 'https://rds.rasch.de/v2/articles/stock.csv?item=440898,204803&qty=1000&fields=id,stock,date'
id,stock,date
440898,839,
204803,1000,

$ curl -o- -u ':KEY' 'https://rds.rasch.de/v2/articles/stock.csv?item=440898,204803&qty=1000&csvSeparator=;&csvHeader=false&fields=id,stock'
"440898";839
"204803";1000