MIME media types are a standard way of describing the format of content on the internet. The full MIME specification is available in RFC 4288.

The Huddle API makes extensive use of media types to advertise and control the format of requests and responses. Every HTTP response that includes a body will contain a content type header that specifies the media-type of the response. Link elements may include a @type attribute to specify the media-type of the linked resource.

Media types have a type, sub-type, and optional suffix.

Huddle-specific media types are all prefixed application/vnd.huddle. Links to images and downloadable files will have a media-type corresponding to the type of the file.

Responses from the Huddle API use the suffix to indicate the encoding of the resource. For example a media-type of application/vnd.huddle.error+xml indicates that the resource is an error and the resource is encoded in XML.

Media types may be parameterised by adding additional data separated by a semi-colon.

In this example, we have a media type of "application/vnd.huddle" which additionally specifies a "version" parameter of "1" and a "describedby" attribute with a URI for schema information.

application/vnd.huddle.data; version=1; describedby="https://schema.huddle.net/rng/folder.rnc"

Sending generic media types, such as application/xml, may result in unexpected behaviour. Avoid using these media wherever possible.

The APIs described by this documentation use the single media type application/vnd.huddle.data for successful requests, and the media type application/vnd.huddle.error for errors.

The media-type application/vnd.huddle.data is documented on the resources overview.

In order to use JSONP (where supported) you have to specify a "callback" querystring parameter.

For example:

GET /localisation/categories/filesappdetails?callback=myfunction HTTP/1.1

.. where myfunction is the name of the javascript function that will be invoked when the response is sent to the client. The response might look something like this:

HTTP/1.1 200 OK
Content-Type: application/javascript

myfunction({bar :{ baz: "qux"}})

When making an HTTP request, you should include an accept header to indicate the resource type and encoding you are expecting.

For example, in this we request, we request XML data from the API.

GET /someresource HTTP/1.1
Accept: application/vnd.huddle.data+xml

The response might looks something like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml

<foo>
  <bar baz="qux" />
</foo>

In this example we request JSON data from the API:

GET /someresource HTTP/1.1
Accept: application/vnd.huddle.data+json

..and the response might look something like this:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  bar :{ baz: "qux"}
}

In this example we request JSONP data from the API:

GET /someresource?callback=myfunction HTTP/1.1

..and the reponse might look something like this:

HTTP/1.1 200 OK
Content-Type: application/javascript

myfunction({bar :{ baz: "qux"}})

Each API operation includes at least one request and response example, including the expected media types as the Content-Type header. Please use these for reference.

Huddle currently supports JSON (and in some cases XML) data encodings.

Huddle currently supports gzip data compression for a number of data encodings. To enable data compression when calling the Huddle API's add the following header to your API request:

Accept-Encoding : gzip, deflate

The data encodings that are supported for data compression are displayed in the following table.