Please sign in or register to access software information via the Iress Community.
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
Xplan Integrations
Details of all the companies who integrate with us
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Iress Open Standard Integration - Technical Overview

antony.nevis
Iress People

 

Document Purpose

This document outlines the technical information on the Iress Open API providing summary client level data to integrators.

 

Introduction

The Iress Open API is an HTTP 1.1 REST API to allow third party systems to integrate with the Xplan platform. The Iress Open API offers access to Xplan’s core business functionality presented in a usable and consistent structure. The semantics and conventions of the Iress Open API should be immediately familiar to programmers accustomed to REST.

Some example use cases of the API are:

  • Back-end system integration
  • Rich web applications running inside a web browser
  • Native applications (Mobile or Desktop)

The Iress Open API is a gateway service that will be hosted in Australia, South Africa and UK. All integrators use the same URL to access Iress Open. The domain name resolves to the closest deployment of Iress Open.

User Acceptance Testing URL (example): https://api.iressopen.com.au/swagger/index.html?urls.primaryName=2.0

The integrator specifies the Xplan Site they wish to integrate with through an HTTP header ‘x-forwarded-host’.

image.png

 

Iress Open App ID

In order to make requests using the Iress Open API, you must first obtain an Iress Open ‘app id’ from Iress. This app id is passed as an HTTP header when you authenticate with Iress Open, this identifies your application to us, and restricts the capabilities of the user you log in with to those required for Iress Open. Each integrator will be provided with a single app id that will be sufficient for both UAT and production environments and will work on all Xplan sites. To use OAUTH2 for authentication an app id per environment is required.

See the Authentication section for more information.

 

API Technical Overview

An overview of information about the HTTP transport used in the API. For more detailed documentation about the resources available please use the following links. Please ensure that the current version is selected top right:

UK Region

https://api.iressopen.co.uk/swagger/index.html?urls.primaryName=3.0

AU Region

https://api.iressopen.com.au/swagger/index.html?urls.primaryName=3.0

ZA Region

https://api.iressopen.co.za/swagger/index.html?urls.primaryName=3.0


The information is presented through the swagger UI. Swagger specification is a commonly used standard for describing APIs and supports code generation:

  • Authentication is performed using OAUTH2 (Authorization Code Grant).
  • The API is accessed using typical JSON API and HTTP 1.1 conventions.
  • Resources are located through hierarchical paths.
  • The actions to be performed on a resource is specified by the HTTP method.
  • Request parameters must be encoded either in the URL’s query component (for GET requests) or, for other method types, in the request body
  • Request bodies containing structured data must be encoded as application/json with the Content-Type HTTP header set accordingly.
  • Responses containing structured data are encoded as application/json.
  • HTTP 1.1 status codes are used to indicate success (using a 2xx code) or error (4xx or 5xx). When an error occurs, HTTP status messages and JSON data in the body may give more information about the problem.

 

HTTP Transport Reference

This section contains a detailed specification of the API transport. The specification described below applies to all interactions with the API.

 

Versioning

The version of the API to use is passed in as a query parameter to the api endpoint as /client?api-version=<version> (e.g. /client?api-version=1.0). If the version query parameter is omitted the default version is assumed. Changing the version may affect global behaviour of the API such as object serialization, default response formats and error codes.

 

Authentication

Integrators authenticate with a specific Xplan Site, using one of two methods supported by Xplan

 

OAUTH2

OAuth 2.0 is a protocol that lets your app request authorisation to private details in a user's Xplan account without getting their password and hence more secure.

The sequence diagram below shows a typical OAUTH integration. This user story demonstrates an Xplan user navigating from Xplan to an integrator’s website, and that website being able to use Iress Open to retrieve data from Xplan.

image.png

You need to register your application with Iress before getting started. A registered application is assigned a unique app id and secret which will be used in the OAuth flow. The Secret should not be shared, and should be stored securely.

You will also need to provide a redirect URI when registering your application with Iress. Xplan will post the access token back to you at your registered redirect URI. You can register a single absolute redirect URI for your application. Should you require more than one url to be registered i.e. for development or staging environments, you will require one app id per environment.

Please see the article Xplan API OAuth 2.0 for how to connect using OAuth 2.

 

Visibility

Requests made to the API are constrained by the visibility of the user used to login to the session - for example, getting a list of docnotes will return the docnotes visible to that user only, not all the docnotes in the system.

 

Requests

Each request made to the API specifies:

  • The resource to operate on (specified by the URL path)
  • The operation to perform (specified by the HTTP method)
  • Parameters that modify the behaviour of the request (query parameters for GET requests, encoded in the request body for other methods).

 

POST and PATCH operations often require Keys to be specified for user-defined types in Xplan, use the supplied options resource e.g. /client/address/options to retrieve a list of valid keys, e.g. for AddressType

 

HTTP methods

HTTP methods specify the operation to perform on a resource. The API supports the following HTTP 1.1 methods:

GET - Retrieve a description of the resource. GET operations have no side-effects (i.e. they are safe according to HTTP 1.1
POST - For a collection of resources, creates a new item in the collection.
PATCH - Update an existing resource by merging the contents of the request with the existing resource. Only the data that is being changed should be send in the request.
DELETE - Delete the resource.

 

Responses

Except where specified in the resource’s documentation, responses to the API are in JSON format.

The structure of the response for a method is specified in the resource’s reference documentation.

 

Success

Xplan’s error codes are consistent with HTTP/1.1 semantics as specified in RFC 7231.

Successful requests will return the following HTTP codes:

 

Code

Meaning

200

Success.

GET will return a copy of the resource in the body.

PATCH will return the id of the item updated.

201

Successful creation. POST to a collection will return a copy id for the newly created item.

204

Success, with an empty body. This is returned by a successful DELETE.

 

Failure

Failed requests will return the following HTTP codes:

Code

Meaning

400

Bad request. The parameters specified by are invalid. This can indicate a problem with malformed syntax (e.g. bad JSON) or invalid arguments being passed. The body of the response will give further details.


This typically indicates an issue with the request, not with Xplan or Iress Open.

401

Unauthorized. The credentials provided were invalid for this resource. If credentials were provided via a session token (via cookie or otherwise), the token may have expired and the client may need to re-authenticate using a username and password. If a username and password were provided to the request that returned 401, they are not valid for this resource - either the login itself is not valid or perhaps the account is locked out.


This typically indicates an issue with the request or configuration/status of the Xplan user account, please contact the site owner to resolve.

403

Permission error. The session does not have sufficient Xplan capabilities to perform the operation. You can check the capabilities of your session by calling the Session endpoint.


This typically indicates an issue with the capabilities configured for the Xplan user you are using, please contact the site owner to resolve.

404

Not found. The resource identified is invalid. Check the URL you are using, could a mis-spelling or if not that then if a resource (client / asset etc) is identified perhaps the resource has been deleted, or is no longer visible to your user.


In the first instance contact the site owner to resolve.

409

Conflict. Another session was updating the resource when this request was executed.


Normally the request will succeed when resent.

500

Unspecified server error.


Please report these errors to Iress so we can improve our service to you.See Technical Support for details on how to report.

502

Upstream server failure. An error occurred when communicating with another server, this may be an unhandled error in Xplan.


Please report these errors to Iress so we can improve our service to you.See Technical Support for details on how to report.

 

As well as the error code, there may be further details returned in the response body that describes the problem in detail. These details will often help you to understand the cause of the error. Do not programmatically scan this string in your app; its contents are subject to change across versions. Rely on the HTTP code only.

{

   "StatusCode": status code,

   "Message": "A message to identify the reason for failure, may be a string or a structure"

}

 

Technical Support

Integrators can raise issues (e.g. an error code is returned) directly to Iress using the Developer Forum.

The process allows Integrators to raise issues with Iress. Iress will need information about the issue or error (see below).

Integrators should supply the following data (where applicable).

  • URL of Iress Open service they are using (i.e. api.open.site.region.iress.online)
  • Date and time of request that failed.
  • Target Xplan site.
  • Username of the user being used.
  • RequestId as returned by Iress Open in HTTP headers. e.g. x-Iress-RequestId:"9e34d227-1e41-11e9-b831-3b763a116d23"
  • The resource requested e.g. /client/1234/asset and the request body if a POST or PATCH
  • The full error details returned including any details in the response body.

 

Security

  • Iress Open does not store any client data. All client data is stored in Xplan.
  • All communication between the integrator and Iress Open and between Iress Open and Xplan uses TLS/SSL to ensure encryption of data in transit.
  • Integrators will automatically use the closest Iress Open service to them.
  • All cookies passed back to the Integrator have cookie protection and are secured with the HTTPOnly and Secure flags.
  • Authorisation is delegated to Xplan to secure and is handled by the existing user mechanism tied in with the permission granted with the associated API key sent in the request. Privilliages for the user come from the Xplan capabilities and licenses associated with the user. (See Authentication section)
  • Iress Open is subject to annual 3rd party penetration tests, as well internal vulnerability assessments as part of any major release.

 

Scalability & Performance

Xplan is deployed to meet expected demand, as such there are limits and Xplan customers should speak to their Iress account managers if there are significant bottlenecks.

Integrators are aware that there are restrictions on the use of the Iress Open service, appropriate use of the service should ensure there is no degradation of performance for Xplan users.

 

Service Availability

Iress Open depends on Xplan, Xplan availability targets, maintenance windows and incident response times are agreed with Xplan site owners.