Basic Principles

This intro describes the general communication with the Immoscout24-RestAPI with examples.

Please use the Postman Collection for executing api requests and oauth authenification, without having to code anything. There's a Tutorial for using the api for building customer websites.

URI structure

Protocol and domain name	https://rest.immobilienscout24.de
technical context	/restapi/api
not technical context	/search
Version	/v1.0
Resource	/expose/{expose_id}
Sub resource of a resource	attachment/{attachment_id}

Example of a complete URI:

http://rest.immobilienscout24.de/restapi/api/search/v1.0/expose/{expose_id}/attachment/{attachment_id}

Authentification

In order to communicate with the IS24-RestAPI, your client has to authentificate per OAuth. If you access data of a user (f.e. exposes of a certain customer, short list and/or saved searches of a user, you need to do 3-legged oAuth. If you have a usecase without a user, than 2-legged oAUth is sufficient. There are official oauth libraries for every language. Here’s a list: http://oauth.net/code. Please keep in mind that every request must be signed.

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:

• 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.
• 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.
• If the resource has been modified since the If-Modified-Since date, the response is exactly the same as for a normal GET.
• 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.

Caching

The resources, that are returned by the API, line real estate objects, short list entries, saved searches, will expire , so we discourage caching on the client side. To minimize response time and network traffic the API supports HTTP Etags and datestamps. If your network library has Etag and datestamp support, we recommend using If-None-Match- or If-Modified-Since-Headers. If one of the clients Etag matches the resource on the server or the resource was not updated since the last request, it will send an empty reply with a 304 Not Modified status. If you have both options of using If-None-Match or If-Modified-Since, we recommend using If-None-Match (Etags).

We offer ETag support for the following resources:

• expose
• shortlistEntry
• Savedsearch

Used status codes

Resource entity exists and has no changes (equal ETag hash):

• "304 Not modified" (No content entity.)

Resource entity does not exist:

• "404 Not found"

Resource entity exists and has changes (different or new ETag):

• "200 OK" (With normal content entity and additional caching information headers.)

Representation

Representations are the supported media or MIME types of a resource. Each resource must have at least one representation. Our web service supports XML (application/xml) and JSON (application/json) by default. JSONP is not supported. We support only UTF-8 as charset encoding.

It is possible that a resource is represented by other or additional media types, e. g. a binary attachment or even multipart encoded data like a picture with a descriptive caption. Please refer to the specific documentation of a resource for related information.

A consumer application (client) must define the MIME type of the representation format by setting the specific HTTP headers:

Accept:

This header defines the representation of requested data (GET) or response data (POST, PUT, DELETE). Accept header and Content-Type may differ; for example you can send data using XML (Content-Type: application/xml) and will get the response body as a JSON representation (Accept: application/json) while creating a new entity of a resource using POST. This is also valid for error messages. It is possible to get a strict representation by adding a variant to the Accept header (Accept: application/xml;strict=true or Accept: application/json;strict=true). Please note: If you request a media type that is not supported by the resource, the server will return a status code of 404 instead of 406.

Content-Type

This header is required if you want to send data to the web service (creating a new entity of a resource with POST or updating an existing entity with PUT). The Content-Type defines the MIME type of the data to send. The given MIME type must match the supported representations of the resource (and file extension is not sufficient).

Strict Representations

List resources, also known as "containers", represent lists of references (hyperlinks) to entities of a specific resource type. The URI path "/shortlist" represents a list of shortlists of an user: an unique identifier is missing. Such a container would return only a list with references and required information. This information does apply to selected resources only.

List resources, also known as "containers", represent lists of references (hyperlinks) to entities of a specific resource type. The URI path "/shortlist" represents a list of shortlists of an user: an unique identifier is missing. Such a container would return only a list with references and required information.

<entries>
<entry id="1" xlink:href="/qualified/path/to/entry/1" mimeType="..." />
<entry id="2" xlink:href="/qualified/path/to/entry/2" mimeType="..." />
...
</entries>

An entity can also contain references to other resources. The URI path "/shortlist/0" represents such an entity: a shortlist with the ID 0.

<entry id="1">
<title>a title<title>
...
<anotherEntry id="123" xlink:href="/qualified/path/to/anotherentry/123" mimeType="..." />
...
</entry>

By default our API delivers a full representation, even on list representations. Because this, a list entry as shown above can contain child notes and additional information - not only the reference and id. This is a business decision to minimize API calls for selected use cases and differs from the REST approach.

If a client only needs a list of references, e. g. to reduce traffic and the data volume, a "strict representation" is required. To get this strict variant, the client must extend the Accept header with the variant "strict=true":

Accept: application/xml;strict=true

or for a strict JSON representation

Accept: application/json;strict=true

Without the strict variant, the list example would look like this (full representation):

<entries>

<entry id="1">

<title>entry 1<title>

...

<anotherEntry id="123" xlink:href="/qualified/path/to/anotherentry/123" mimeType="..." />

...
</entry>
<entry id="2">
<title>entry 2<title>
...
<anotherEntry id="456" xlink:href="/qualified/path/to/anotherentry/456" mimeType="..." />
...
</entry>
...
</entries>

Path parameters

Path parameters are used to identify entities, represent hierarchies or to provide data to a resoure. They are not intended to filter or restrict information like query parameters (see below). Please do not confuse path parameters with sub resources. A resource can have more than one path parameter, e. g. to represent hierarchical data. Sometimes it is required to supply more than one parameter to a resource for an unique identification of an entity. Examples:

A resource:

/resource

An entity of a resource (the {id} is a path parameter of the resource):

/resource/{id}

A resource that represents a geo hierarchy (with two path parameters:/key/{value}):

/resource/continent/{Europe}/country/{Germany}

Encoding of path parameters

Many values (like usernames) in the path of the URL must be encoded. We use the so called percent encoding

• encode space as %20, not as "+"
• don't encode "@" (it is allowed in the path)
• semicolon ";" must be encoded to %3B (this may change in the future)

See also:

• http://stackoverflow.com/questions/4669692/valid-characters-for-directory-part-of-a-url-for-short-links
• http://tools.ietf.org/html/rfc2396#section-2.1
• http://tools.ietf.org/html/rfc3986#section-2.1

You may use gdata java client's CharEscapers

/**
* The regular Spring UriComponentsBuilder encoding ignores semicolons.
*@param pathSegment
*@return
*/
public static String encodePathsegment(String pathSegment) {
  return CharEscapers
  .uriEscaper(false) // false means "no plusForSpace", so %20 .escape(pathSegment);
}

Example

A resource that represents a geo hierarchy (with one path parameter representing continents). A GET requests retrieves a list (of xlink references) to all continents:

/resource/continent

A resource that represents a geo hierarchy (with two path parameters representing a continent). A GET requests retrieves the information for the given continent in a specified reprensentation:

/resource/continent/Europe

A resource that represents a geo hierarchy (with three path parameters representing countries of a given continent). A GET requests retrieves a list (of xlink references) to all countries of this continent:

/resource/continent/Europe/country

A resource that represents a geo hierarchy (with four path parameters representing a country). A GET requests retrieves the information for the given country in a specified reprensentation (Note: the country is only unique if you provide the whole hierarchy represented by the path parameters!):

/resource/continent/Europe/country/Germany

A resource that represents a geo hierarchy (with fife path parameters representing states of a given country). A GET requests retrieves a list (of xlink references) to all states of this country:

/resource/continent/Europe/country/Germany/region

To filter the returned states you can use query parameters. E. g. return all states starting with B:

/resource/continent/Europe/country/Germany/region?q=B

This should return the following German federal states: Baden-Würtemberg, Bayern, Berlin, Brandenburg, Bremen. Note: continent, country, and region are path parameters (consisting of a key and a value) in this example and not sub resources.

Query parameters

Query parameters are used to filter or to restrict information of a resource. They are not intended to identify entities of a resource or to select the representation. Do not use query parameters to identify resource entities! For example, in a search request each query parameter represents a search criterion and restricts the result list - like a filter. Unknown search criteria are ignored (see Query string extensibility) or results in an empty result list.

There are four types of query parameters:

• ranges: key=minimalValue-maximalValue (use the - sign between the minimum and maximum value of your range. If one side is empty -## or ##-, then is this meaning from the lowest value or to the highest value of the parameter.)
• single parameters: key=value
• ordered lists (e. g. ranges): key=value1;value2;value3;...
• unordered lists (e. g. enumerations): key=value3,value1,value2,...

Note about separators: Members of ordered enumeration types are separated with a semicolon (";"), unordered enumeration types are separated with a comma (","). Query parameters (key-value-pairs) are separated with ampersand ("&").

Note about number values: floating point number values (like longitude/latitude) use the dot (".") as decimal separator (example: geocoordinates=52.512303;13.431191;1). No separator between thousands (example: 12000.123).

Query string extensibility

Query string extensibility means, that a service should ignore any query parameters it does not understand.

An use case is to pass query paramters to subsequent API calls, if the service consumes other services. This allows to add new functionality without breaking existing services.

URI-Specified representation

A client can specify the representation using a query string or as an suffix of the URI:

http://domain:port/path?parameters.xml

The suggested way is to use the specific HTTP Accept or HTTP Content-Type header. For consistency and interoperability concerns, it is important not to mix this TUK-based approach with our standard approach that uses conformant HTTP headers.

XML

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 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.
• 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.