Tutorials, SDKs and Plugins

Java-SignPost

This tutorial shows how to connect to the IS24 object API using signpost. Please note, that immobilienscout24 does not offer support for this tutorial.

Getting the dependencies

This tutorial assumes that you are using Maven. You can use the following settings in the pom.xml of your project. Please use at least version 1.2.1.1 as 1.2 may lead to some problems.

 

<dependencies>

<dependency>

<groupId>oauth.signpost</groupId>

<artifactId>signpost-core</artifactId>

<version>1.2.1.1</version>

</dependency>

<dependency>

<groupId>oauth.signpost</groupId>

<artifactId>signpost-commonshttp4</artifactId>

<version>1.2.1.1</version>

</dependency>

</dependencies>

 

 

 

URLs for sandbox environment

The named URLs in this tutorial are for the productive environment. If your work within the sandbox environment, then please use http://sandbox-immobilienscout24.de instead of http://rest.immobilienscout24.de.  

 

 

Consumer and Provider

First we need to create a consumer and a provider object. If you are not familiar with these terms, please visit this page. The consumer will be created as DefaultOAuth consumer. You need to pass in your oauthkey and -secret. You can obtain these by the api registration. If you want to use the import-export-REST-API in order to edit real estate objects, than send a mail to service@immobilienscout24.de in order to obtain a sandbox access first.

OAuthConsumer consumer = new DefaultOAuthConsumer("<YOUR-TEST-ACCESS-KEY>", "<YOUR-TEST-ACCESS-SECRET>");

 


Next we will create a provider object. The constructor take three arguments which are the request-, access-, and confirm URL of the API

 

OAuthProvider provider = new DefaultOAuthProvider("http://rest.immobilienscout24.de/restapi/security/oauth/request_token", "http://rest.immobilienscout24.de/restapi/security/oauth/access_token", "http://rest.immobilienscout24.de/restapi/security/oauth/confirm_access");

 

Now we will request the request token from the API. This is done by calling OAuthProvider.retrieveRequestToken(...) and passing the consumer and the your callback URL as paramters. To ensure that the callback is called correctly always use an URL with "http://" prefix and not only the server name.

Note: In this example we do not have an own server which handles the callback. To make this example simple we just call an existing URL. The API will add the paramaters to this URL.

 

System.out.println("Fetching request token...");

String authUrl = provider.retrieveRequestToken(consumer, "http://www.google.de");

//provide your own callback url here

String requestToken = consumer.getToken();

String requestTokenSecret = consumer.getTokenSecret();

System.out.println("Request token: " + requestToken);

System.out.println("Token secret: " + requestTokenSecret);

 

The provider will return the request credentials and an URL the consumer must send to the resource owner (user) to enable him to log into the provider and grant access to the consumer. We will simply print out the url and perform the request manually.

 

 

System.out.println("Now visit:\n" + authUrl + "\n... and grant this app authorization");

System.out.println("Enter the verification code and hit ENTER when you're done:");


Copy the printed URL to your browser. You will be delegated to the IS24 login form. Just type in your IS24 credentials. The system now delegates you a pages where you need to grant access to your application. Remember that we provided a callback url when requesting the request credentials? After you granted access the provider (IS24 object API) will delegate to this callback url. As we used google we will get something like the following:

http://www.google.de/?oauth_token=abcdefghijklm&oauth_verifier=vTAlhl&state=authorized


To request the access credentials we need to use the "oauth_verifier" parameter provided in the callback.

Note: In a real system this callback is delegated to you application which reads out the data.


In our example we will read the oauth token from the command line. Now we can use the token to request the access credentials. This is done ba calling OAuthProvider.retrieveAccessToken(...) and pass in the consumer and the token similar to the request credentials call. The access credentials will be stored in the consumer object. The request credentials will be overwritten.

 

 

BufferedReader br = new BufferedReader(new InputStreamReader(System.in));

String verificationCode = br.readLine();

System.out.println("Fetching access token...");

provider.retrieveAccessToken(consumer, verificationCode.trim());

String accessToken = consumer.getToken();

String accessTokenSecret = consumer.getTokenSecret();

System.out.println("Access token: " + accessToken);

System.out.println("Token secret: " + accessTokenSecret);

 

Actually we are done. We now have requests access to the users resources using three-legged oauth. Now we can sign requests and use the API. Requests are signed using our consumer object. After the request is signed you can use it the establish the connection.

 

 

URL url = new URL("http://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate"); HttpURLConnection apiRequest = (HttpURLConnection) url.openConnection(); consumer.sign(apiRequest); System.out.println("Sending request..."); apiRequest.connect(); System.out.println("Response: " + apiRequest.getResponseCode() + " " + apiRequest.getResponseMessage());

 

Complete Example Code

 

package de.immobilienscout24.example.consumer.webapp.tester;

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStreamReader;

import java.io.UnsupportedEncodingException;

import java.net.HttpURLConnection;

import java.net.MalformedURLException;

import java.net.URL;

import oauth.signpost.OAuthConsumer;

import oauth.signpost.OAuthProvider;

import oauth.signpost.basic.DefaultOAuthConsumer;

import oauth.signpost.basic.DefaultOAuthProvider;

import oauth.signpost.exception.OAuthCommunicationException;

import oauth.signpost.exception.OAuthExpectationFailedException;

import oauth.signpost.exception.OAuthMessageSignerException;

 

public class OauthTesterIS24 { public static void main(String[] args) throws Exception{

OAuthConsumer consumer = new DefaultOAuthConsumer("{your oAuthKey}", "{your oAuthSecret}");

OAuthProvider provider = new DefaultOAuthProvider("http://rest.immobilienscout24.de/restapi/security/oauth/request_token", "http://rest.immobilienscout24.de/restapi/security/oauth/access_token", "http://rest.immobilienscout24.de/restapi/security/oauth/confirm_access");

System.out.println("Fetching request token...");

String authUrl = provider.retrieveRequestToken(consumer, "http://www.google.de");

String requestToken = consumer.getToken();

String requestTokenSecret = consumer.getTokenSecret();

System.out.println("Request token: " + requestToken);

System.out.println("Token secret: " + requestTokenSecret);

System.out.println("Now visit:\n" + authUrl + "\n... and grant this app authorization");

System.out.println("Enter the verification code and hit ENTER when you're done:");

BufferedReader br = new BufferedReader(new InputStreamReader(System.in));

String verificationCode = br.readLine();

System.out.println("Fetching access token...");

provider.retrieveAccessToken(consumer, verificationCode.trim());

String accessToken = consumer.getToken();

String accessTokenSecret = consumer.getTokenSecret();

System.out.println("Access token: " + accessToken);

System.out.println("Token secret: " + accessTokenSecret);

System.out.println("first call"); requestObjectApi(consumer);

System.out.println("second call"); requestObjectApi(consumer);

System.out.println("third call"); OAuthConsumer consumer2 = new DefaultOAuthConsumer({your oAuthKey}", "{your oAuthSecret});

consumer2.setTokenWithSecret(accessToken, accessTokenSecret);

requestObjectApi(consumer2);}

 

private static void requestObjectApi(OAuthConsumer consumer) throws MalformedURLException, IOException, OAuthMessageSignerException, OAuthExpectationFailedException, OAuthCommunicationException, UnsupportedEncodingException {

System.out.println("#################################################################################################"); URL url = new URL("http://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate");

HttpURLConnection apiRequest = (HttpURLConnection) url.openConnection();

consumer.sign(apiRequest);

System.out.println("Sending request...");

apiRequest.connect();

System.out.println("Expiration " + apiRequest.getExpiration());

System.out.println("Timeout " + apiRequest.getConnectTimeout());

System.out.println("URL " + apiRequest.getURL());

System.out.println("Method " + apiRequest.getRequestMethod());

System.out.println("Response: " + apiRequest.getResponseCode() + " " + apiRequest.getResponseMessage());

System.out.println("#################################################################################################");

}

 

}

 

Using a existing access credentials

If your application stores the access and uses it later to sign request you need to care for two things. First you need to set the credentials using the OAuthConsumer.setTokenWithSecret(...) method. Second you need to change the provider to use Oauth 1.0a as the API uses this version. After you have done these changes you can sign request to the API.

 

OAuthConsumer consumer = new DefaultOAuthConsumer("{your oAuthKey}", "{your oAuthSecret}");

consumer2.setTokenWithSecret(requestToken, requestTokenSecret);

OAuthProvider provider = new DefaultOAuthProvider("http://rest.immobilienscout24.de/restapi/security/oauth/request_token", "http://rest.immobilienscout24.de/restapi/security/oauth/access_token", "http://rest.immobilienscout24.de/restapi/security/oauth/confirm_access");

provider2.setOAuth10a(true);

provider2.retrieveAccessToken(consumer2, verificationCode.trim());