Basic Principles

XML & JSON

By default, our REST API supports JSON and XML as representation formats and UTF-8 as charset encoding. Other resource specific types are possible, but optional (please refer to the specific documentation of the resource).

XML

To use the XML representation, the client must set the following HTTP header (GET requests):

Accept: application/xml

If you want to write data (using POST or PUT) you must provide the following HTTP headers:

Accept: application/xml

Content-Type: application/xml

It's possible, but not suggested, that you send data in XML and retrieve the response as JSON by providing another specific Accept header. Please never use "*/*" for the Accept header or the Content-Type header; you could get undefined results.

Important Notes

  • A client should never validate against the given schema; each change in the web service's schema would break the validation on client side.
  • Please ensure that you use the correct charset encoding (we use UTF-8 by default).
  • In general, the XML representation can support binary content using BASE64 encoded inline data (i. e. for included images). REST forbids this approach, because an image is always a resource or is related to another resource. It's suggested to use "multipart/form-data" or "multipart/mixed" for such media types. In addition you can provide meta information (like a title or description) for an uploaded media file using a POST or PUT request. If you have no meta data it is sufficient to use a binary stream (i. e. image/jpeg) if the resource supports it.
  • For technical reasons the server will return a status code of 404 instead of 406, if you provide a not supported mime type as Accept header.

JSON

By default, our REST API supports JSON and XML as representation formats and UTF-8 as charset encoding. Other resource specific types are possible, but optional (please refer to the specific documentation of the resource).

To use the JSON representation, the client must set the following HTTP header (GET requests):

Accept: application/json

If you want to write data (using POST or PUT) you must provide the following HTTP headers:

Accept: application/json
Content-Type: application/json

It's possible, but not suggested, that you send data in JSON and retrieve the response as XML by providing another specific Accept header. Please never use "*/*" for the Accept header or the Content-Type header; you could get undefined results.

  • Important Notes
  • A client should never validate against the given schema; each change in the web service's schema would break the validation on client side.
  • JSON-specifc characters can be escaped by using a backslash (e. g. "/" = "\/"). Please ensure that you use the correct charset encoding (our web service and JSON are using UTF-8 by default).
  • JSON currently supports no xsi:type attributes to identify - for example - the type of a real estate or other related complex types, if you retrieve data. If you want to modify retrieved JSON objects, you must add the specific xsi:type (e. g. xsi:type search:HouseBuy) to the specific member before transmitting the modified data. Otherwise the validation fails.
  • In general, the JSON representation type can support binary content using BASE64 encoded inline data (i. e. for included images). REST forbids this approach, because an image is always a resource or is related to another resource. It's suggested to use "multipart/form-data" or "multipart/mixed" for such media types. In addition you can provide meta information (like a title or description) for an uploaded media file using a POST or PUT request. If you have no meta data it is sufficient to use a binary stream (i. e. image/jpeg) if the resource supports it.
  • Currently JSONP is not supported.
  • For technical reasons the server will return a status code of 404 instead of 406, if you provide a not supported mime type as Accept header.