Usage in General

Notes about general usage

The following page shows some general examples how to connect and authorize at the Webservice. Besides this you can find further examples at the Import/Export API usage page.

Create a client instance

In the first step, you need to create a client, that communicates with the Webservice.

Create default client

import org.openestate.is24.restapi.AbstractClient;
import org.openestate.is24.restapi.DefaultClient;

public class DefaultClientExample
{
  final static String WEBSERVICE_URL = AbstractClient.LIVE_API;
  final static String CONSUMER_KEY = "my consumer key";
  final static String CONSUMER_SECRET = "my consumer secret";

  public static void main( String[] args )
  {
    AbstractClient client = new DefaultClient(
      WEBSERVICE_URL, CONSUMER_KEY, CONSUMER_SECRET );

    // do something useful with the client
  }
}

(extracted from DefaultClientExample.java)

Create the client for Apache HttpClient 4.5:

import org.openestate.is24.restapi.AbstractClient;
import org.openestate.is24.restapi.hc4.HttpComponents4Client;

public class HttpComponents43ClientExample
{
  final static String WEBSERVICE_URL = AbstractClient.LIVE_API;
  final static String CONSUMER_KEY = "my consumer key";
  final static String CONSUMER_SECRET = "my consumer secret";

  public static void main( String[] args )
  {
    AbstractClient client = new HttpComponents4Client(
      WEBSERVICE_URL, CONSUMER_KEY, CONSUMER_SECRET );

    // do something useful with the client
  }
}

(extracted from HttpComponents4ClientExample.java)

Create access token on first use

Before the client can connect to an agency account at IS24, the owner of the agency needs to grant access to his data. Therefore an access token must be created on the first connection.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import oauth.signpost.exception.OAuthException;
import org.openestate.is24.restapi.AbstractClient;
import org.openestate.is24.restapi.DefaultClient;
import org.openestate.is24.restapi.utils.Authorization;
import org.openestate.is24.restapi.utils.Verification;

public class VerificationExample
{
  final static String WEBSERVICE_URL = AbstractClient.LIVE_API;
  final static String CONSUMER_KEY = "my consumer key";
  final static String CONSUMER_SECRET = "my consumer secret";
  final static String CALLBACK_URL = "http://mywebsite.com/is24-callback.php";

  public static void main( String[] args )
  {
    AbstractClient client = new DefaultClient(
      WEBSERVICE_URL, CONSUMER_KEY, CONSUMER_SECRET );

    // request a verification from the webservice
    Verification v = null;
    try
    {
      v = client.fetchVerification( CALLBACK_URL );
    }
    catch (OAuthException ex)
    {
      throw new RuntimeException( "Can't fetch verification!", ex );
    }
    System.out.println( "Visit the following URL to verify access to an agency account at IS24:" );
    System.out.println( v.verificationUrl );
  }
}

(extracted from VerificationExample.java)

The Webservice responds to client.fetchVerification( CALLBACK_URL ) with a unique URL, that the user must open in his web-browser. In the web-browser the user must enter his login credentials from IS24 (if he is not already logged in). Afterwards he is asked to grant access to your application.

After access was granted or denied by the user, the web browser is redirected to the URL, that was provided as CALLBACK_URL. IS24 appends the following parameters to the redirection URL:

• The parameter state contains the value authorized, if the user has granted access.
• The parameter oauth_verifier contains the verification code, if the user has granted access.
• The parameter oauth_token contains the token of the verification process.

You can find an example PHP script, that handles those callbacks from IS24 and shows the verification code to the user at etc/php/is24-callback.php.

After the user finished the verification process in his web browser and received a verification code, the application can access the Webservice like that:

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import oauth.signpost.exception.OAuthException;
import org.openestate.is24.restapi.AbstractClient;
import org.openestate.is24.restapi.DefaultClient;
import org.openestate.is24.restapi.utils.Authorization;
import org.openestate.is24.restapi.utils.Verification;

public class VerificationExample
{
  final static String WEBSERVICE_URL = AbstractClient.LIVE_API;
  final static String CONSUMER_KEY = "my consumer key";
  final static String CONSUMER_SECRET = "my consumer secret";
  final static String CALLBACK_URL = "http://mywebsite.com/is24-callback.php";

  public static void main( String[] args )
  {
    AbstractClient client = new DefaultClient(
      WEBSERVICE_URL, CONSUMER_KEY, CONSUMER_SECRET );

    // request a verification from the webservice
    Verification v = null;
    try
    {
      v = client.fetchVerification( CALLBACK_URL );
    }
    catch (OAuthException ex)
    {
      throw new RuntimeException( "Can't fetch verification!", ex );
    }
    System.out.println( "Visit the following URL to verify access to an agency account at IS24:" );
    System.out.println( v.verificationUrl );

    // read verification code from command line
    String verificationCode = null;
    System.out.println("Please enter your verification code: ");
    try
    {
      BufferedReader bufferRead = new BufferedReader(new InputStreamReader(System.in));
      verificationCode = bufferRead.readLine();
    }
    catch(IOException ex)
    {
      throw new RuntimeException( "Can't read verification code!", ex );
    }

    // fetch access tokens and authorize at the webservice
    Authorization a = null;
    try
    {
      a = client.authorizeAfterVerification( v, verificationCode );
    }
    catch (OAuthException ex)
    {
      throw new RuntimeException( "Can't fetch authorization!", ex );
    }
    System.out.println( "The access token was created." );
    System.out.println( "token  : " + a.accessToken );
    System.out.println( "secret : " + a.accessTokenSecret );

    // from now on the webservice is accessible for the client
  }
}

(extracted from VerificationExample.java)

The call of client.fetchVerification( v, verificationCode ) returns an access token and access secret for the user and his agency account. These values can be used for future connections with the Webservice for the user / agency. You should store these values at a safe place in your application.

Connect with an access token

After the verification process was finished for a user / agency, you should have an access token and access secret. These values can be used for any connections in the future for that certain user / agency.

import oauth.signpost.exception.OAuthException;
import org.openestate.is24.restapi.AbstractClient;
import org.openestate.is24.restapi.DefaultClient;

public class AuthorizationExample
{
  final static String WEBSERVICE_URL = AbstractClient.LIVE_API;
  final static String CONSUMER_KEY = "my consumer key";
  final static String CONSUMER_SECRET = "my consumer secret";
  final static String ACCESS_KEY = "user's access key";
  final static String ACCESS_SECRET = "user's access secret";

  public static void main( String[] args )
  {
    AbstractClient client = new DefaultClient(
      WEBSERVICE_URL, CONSUMER_KEY, CONSUMER_SECRET );

    // authorize at the webservice with the access token
    try
    {
      client.authorize( ACCESS_KEY, ACCESS_SECRET );
    }
    catch (OAuthException ex)
    {
      throw new RuntimeException( "Authorization failed!", ex );
    }

    // from now on the webservice is accessible for the client
  }
}

(extracted from AuthorizationExample.java)