Basic Principles

Header

HTTP Headers

Authorization

Used to supply credentials for user or system authentication. Note: Use only secure SSL connections.

Authenticate: Basic user:password (Base64 encoded)

WWW-Authorize

Returns the supported authentication schemes and named realms of a protected resource.

WWW-Authenticate: Basic="IS24 realm", ...

Location

The Location response-header field is used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. For 201 (Created) responses, the Location is that of the new resource which was created by the request (e. g. a POST request to create a new resource). For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource. The field value consists of a single absolute URI to the new created entity of the resource:

Location: http://rest.immobilienscout24.de/restapi/api/search/v1.0/searcher/test@is24.de

Accept

If you want to retrieve information using GET, this header defines the media type or representation of the data:

Accept: application/json

You can get a strict representation by adding the following variant to the header value:

Accept: application/xml;strict=true

or

Accept: application/json;strict=true

If the requested representation is not supported by the resource, a status "415 Unsupported Media Type" is returned. Note: The Accept and Content-Type header can be different. For technical reasons the server will return a status code of 404 instead of 406 or 415, if you provide a not supported mime type as Accept header. Not all resources support a strict representation.

Content-Type

This header defines the media type or representation of the load, you want to transmit to the web service using POST (Create) or PUT (Update). If this header is missing, a status "415 Unsupported Media Type" is returned. Note: The Accept and the Content-Type header can be different.

Content-Type: application/xml

A missing Content-Type header in POST or PUT requests may lead to an oAuth-error, saying Invalid signature.

ETag

See http://en.wikipedia.org/wiki/HTTP_ETag for more information

ETag: BASE64_HASH

If-Modified-Since

This header is used with GET requests, to make them conditional: if a requested resource has not been modified since a given time specified by this header, the requested resource will not be transferred to the client. Instead, the response code "304 Not modified" will be returned with no entity body.

The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead.

The algorithm for determining this includes the following:

  1. A given date (provided by the If-Modified-Since header from the client) which is later than the server's current time is invalid. Ensure that you provide the correct time zone/ daylight savings time.
  2. If the request would normally result in anything other than a "200 OK", or if the passed If-Modified-Since date is invalid (see above), the response is exactly the same as for a normal GET.
  3. If the resource has been modified since the If-Modified-Since date, the response is exactly the same as for a normal GET.
  4. If the resource has not been modified since a valid If-Modified-Since date, the server must return a "304 Not modified" response without entity body.

If-Modified-Since: Thu, 31 Mar 2011 23:59:59 GMT

Refer to http://www.faqs.org/rfcs/rfc2822 for the correct date time format used in the If-Modified-Since header.

 

IS24 specific Headers

TBD