API: Media Types - QutEcoacoustics/baw-server GitHub Wiki

There are multiple media types that can be returned from the API.

These can be negotiated either with:

  • The Accept header
  • By appending an extension on to the endpoint
    • e.g. /projects.json or /projects.csv

JSON

JSON is the stanard media type for most endpoints.

CSV

CSV is supported for some specialized endpoints.

Experimental CSV support for list endpoints

#index (listing) and #filter (filter endpoints) also support returning results in CSV format.

Tips for working with CSV:

  • No meta object is included in the response (only data)
  • The disable_paging=true flag is recommended - though take care when exporting very large datasets
  • CSV formats will automatically include content disposition headers and a suggested file name
  • You can use API: Filtering parameters to customize the CSV colums returned

HTML

Some routes return HTML, even by default.

Any pages doing this should be considered deprecated and should be replaced by a RESTful JSON API.

Form Data

Some routes that are not covered by an API still accept multipart/form-data request bodies.

Those routes should be considered deprecated and should be replaced by a RESTful JSON API.

<Binary formats>

Some routes return binary data. These routes typically serve multimedia:

  • images
  • audio
  • or arbitrary media types (e.g. in analysis results endpoints)

The only route that supports media type negotion is the .../media endpoint. See API: Media.