Application Program Interface

1. Scope

1.1 Identification

This document identifies the Application Programming Interface (“API”) available to third-party clients for integration with the Property Plus Framework (“Framework”) infrastructure.

1.2 System Overview

The API provides a secure HTTPS gateway for communicating with Framework, sending and receiving data in XML format.

Most programming languages can accommodate such HTTPS / XML communication, allowing programmers to develop their applications to communicate directly with Framework by issuing commands as specified in this document.

1.3 Document Overview

This document will explain how to:

Authenticate access to Framework
Retrieve data from Framework
Send data to Framework

2. Connecting to Framework

In order to make a connection to Framework you will need the following:

A specific URL (the “Cluster URL”) that identifies the domain and directory that hosts the customer database with which the API is to communicate
- Typically, this will be https://my.property-plus.com/clients
A Database name that is unique to this Cluster for this customer
User credentials that are authorised to access this Database

These details will have been provided to the user or their administrator.

2.1 API URL

The API URL is constructed from the Cluster URL appended with a consistent endpoint/script, which is “api.pl”.

For example, if the Cluster URL is: https://my.property-plus.com/clients,

the API URL is: https://my.property-plus.com/clients/api.pl

2.1.1 Validation

Communication with Framework will be accepted only via well-formed XML, which must be in the following basic format:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database></database>
           <username></username>
           <password></password>
</authenticate>
<command></command>
</api>

The format of authenticate and command XML elements are explained in the following sections.

Note the following:

XML must be posted to the specified API URL
XML is validated by https://www.w3schools.com/xml/xml_validator.asp
XML must include the standard DTD ?xml line with no leading spaces or carriage returns at the start of the file
XML element names are always lower case
There must be no leading/trailing white space in element data
Indentation of and line spacing between XML elements is optional
The
element must include the API version number that is to be used
- See Release History for details
XML must include only one authenticate element
XML must include only one command element
Command-specific elements must be formatted as explained in the following sections
You may include other elements for your own purposes providing that they do not conflict with the names of elements defined in this document, but they will be ignored

Validation checks are carried out in following sequence:

Check for well-formed XML
Check for valid authentication
Check the operation defined in the API version specified in the version element data
Check for correct and complete data in the submitted command

If the XML passes validation, a success response in the following format will be returned:

If the XML fails validation, an error response in the following format will be returned:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2024-04-30 12:00:00</datetime>
<response>
           <success>0</success>
           <errorcode>200</errorcode>
           <errortext>Invalid XML code</errortext>
</response>
</api>

2.1.2 Authentication

In this section we specify the authenticate XML element that must be included in every communication with Framework. It has the following format:

<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>

Note the following:

database This identifies the name of the target database with which to communicate
username This is the name with which the user logs in to Framework and can be one of:
                          DATABASE.USER   a specific named user of the target database
                          DATABASE              assumes the admin user of the target database
                          OTHERCO.USER   a specific named user of a cluster-admin database*
                          OTHERCO               assumes the admin user of a cluster-admin database*
password This is the password associated with the submitted username

* Framework infrastructure allows for “super users” to log in to other users’ databases in the same cluster. If OTHERCO does not match DATABASE, it is assumed that OTHERCO.USER is a super user wishing to communicate with DATABASE. Authentication will fail if OTHERCO.USER is not a super user in the specified cluster.

2.2 Retrieve Data from Framework: Get Commands

This section describes the commands that are available to a third party to return data in XML format from the specified database.

Please contact us if you find that you need commands that are not included in this document.

If the XML passes authentication, the target database will return the requested data in XML format and a success response code in XML format.

Each sub-section includes an example complete XML for the individual command and a table that specifies the format of the data that is returned.

The individual get commands, <get>…</get>, may be included in a larger XML submission of multiple commands.

Each individual get command may be modified with one or many conditions, <condition>…</condition>. The final sub-section describes conditions.

2.2.1 GET_PP_PROPERTIES

To return a listing of all Properties and their details:

Name	Type	Example	Description
p_id	int(10)	1	Internal record ID
p_ref	varchar(255)	PROP123	Property Reference
p_name	varchar(255)	Main Branch	Property Name
p_add1	varchar(255)	High Street	Property Address Line 1
p_add2	varchar(255)		Property Address Line 2
p_posttown	varchar(255)	London	Property Address Post Town
p_postcode	varchar(255)	NW1	Property Address Postcode
p_modified	timestamp	2024-04-30 12:00:00	System datetime this record was last modified

Example response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<datetime>2024-04-30 12:00:00</datetime>
<success>1</success>
<number_of_rows>2</number_of_rows>
<table>pp_properties</table>
<row>
</row>
<row>
</row>
</api>

2.2.6 GET Conditions

Every GET command may be modified by setting a number of conditions, which will have the effect of filtering the data that is returned by the command. This is probably best illustrated by an example. Say you want to retrieve a list of customers whose details have been modified after a certain date. The following XML will achieve this response:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<api>
<version>1.03</version>
<authenticate>
           <database>DATABASE</database>
           <username>USERNAME</username>
           <password>PASSWORD</password>
</authenticate>
<get>
           <command>GET_PP_PROPERTIES</command>
           <condition>
                       <field>c_modified</field>
                       <operator>gt</operator>
                       <value>2024-04-30 12:00:00</value>
         </condition>
</get>
</api>

See that the condition element is applied after the command element within the get block. The condition has three components, which should be quite clear to understand:

<field>, which is the field name as specified in the relevant section above
<operator>, which is a logical operator as specified in the table immediately below
<value>, which must be in the same format as the specified field

Note that the condition element can also be written in a single line:

Operator	Description	Applied to
gt	Is greater than	Integer, number, date, time, datetime fields
lt	Is less than	Integer, number, date, time, datetime fields
equal	Is equal to	Integer, number, date, time, datetime, text fields
notequal	Is not equal to	Integer, number, date, time, datetime, text fields
like	Includes	Text fields
notlike	Does not include	Text fields

Text operators are not case sensitive, i.e. <value>text</value> and <value>TEXT</value> would return the same result.

Multiple conditions are applied with the AND logical operator, i.e. a record will be returned only if all conditions are met.

2.3 Send data to Framework: Post Commands

This section describes the commands that are available to a third party to send data in XML format to the specified database.

Please contact us if you find that you need commands that are not included in this document.

If the XML passes authentication, the target database will be updated with the data being sent and a success response code in XML format will be returned.

Each sub-section includes an example complete XML for the individual command and a table that specifies the format of the data that is submitted.

The individual post commands, <post>…</post>, may be included in a larger XML submission of multiple commands.

2.3.1 PP_PROPERTY_NEW

Create a new customer with basic records: