Hi Guys,
I’m new as of around five minutes ago and a front end developer so my PHP knowledge is pretty much limited to contact forms, if I’m posting wrong please let me know for the future and if I’m not making sense at any point please let me know there too 
.
I have a client for which I’m building a website and I need to connect with their API, I have the initial connection working within my server space but then I have to make calls to their API and I’m really not sure what I’m doing, I don’t imagine this is difficult for someone who knows what they’re doing with it, I’ll post the PHP I was initially given below followed by the relevant parts of the documents regarding the API calls, any help at even just pointing me in the right direction would be very much appreciated and thank you for reading.
<?php
/*
Vebra XML API Integration With PHP Example
Author: Joe Harvey
Last Modified: 20-10-2011
READ ME:
- Please enter your login credentials and Data Feed ID below
- The following functions will attempt to connect to the given URL using a token stored in a session value
- If no session value exisits then it will request one.
- Returned tokens are written to a text file along with their approximate start and expire times for your reference
- Returned headers and returned XML (on success) are also written to txt files
- All of these files are saved to the parent folder where you run this script from. You must ensure that folder has Write permissions!
- Should you loose you session token (by clearing cookies and/or closing the browser) you can enter the token manualy from the tokens.txt file
*/
session_start();
//Define Your Unique Variable Here:
$username = "";
$password = "";
$datafeedID = "";
$request = "http://webservices.vebra.com/export/$datafeedID/v1/branch";
//Function to authenticate self to API and return/store the Token
function getToken($url) {
//Re-define username and password variable scope so they can be used within the function
global $username, $password;
//Overwiting the response headers from each attempt in this file (for information only)
$file = "headers.txt";
$fh = fopen($file, "w");
//Start curl session
$ch = curl_init($url);
//Define Basic HTTP Authentication method
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
//Provide Username and Password Details
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
//Show headers in returned data but not body as we are only using this curl session to aquire and store the token
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_NOBODY, 1);
//write the output (returned headers) to file
curl_setopt($ch, CURLOPT_FILE, $fh);
//execute curl session
curl_exec($ch);
// close curl session
curl_close($ch);
//close headers.txt file
fclose($fh);
//read each line of the returned headers back into an array
$headers = file('headers.txt', FILE_SKIP_EMPTY_LINES);
//for each line of the array explode the line by ':' (Seperating the header name from its value)
foreach ($headers as $headerLine) {
$line = explode(':', $headerLine);
$header = $line[0];
$value = trim($line[1]);
//If the request is successful and we are returned a token
if($header == "Token") {
//save token start and expire time (roughly)
$tokenStart = time();
$tokenExpire = $tokenStart + 60*60;
//save the token in a session variable (base 64 encoded)
$_SESSION['token'] = base64_encode($value);
//For now write this new token, its start and expiry datetime into a .txt (appending not overwriting - this is for reference in case you loose your session data)
$file = "tokens.txt";
$fh = fopen($file, "a+");
//write the line in
$newLine = "'".$_SESSION['token']."','".date('d/m/Y H:i:s', $tokenStart)."','".date('d/m/Y H:i:s', $tokenExpire)."'"."\n";
fwrite($fh, $newLine);
//Close file
fclose($fh);
}
}
//If we have been given a token request XML from the API authenticating using the token
if (!empty($_SESSION['token'])) {
connect($url);
} else {
//If we have not been given a new token its because we already have a live token which has not expired yet (check the tokens.txt file)
echo '<br />There is still an active Token, you must wait for this token to expire before a new one can be requested!<br />';
}
}
//Function to connect to the API authenticating ourself with the token we have been given
function connect($url) {
//If token is not set skip to else condition to request a new token
if(!empty($_SESSION['token'])) {
//Set a new file name and create a new file handle for our returned XML
$file = "test.xml";
$fh = fopen($file, "w");
//Initiate a new curl session
$ch = curl_init($url);
//Don't require header this time as curl_getinfo will tell us if we get HTTP 200 or 401
curl_setopt($ch, CURLOPT_HEADER, 0);
//Provide Token in header
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Basic '.$_SESSION['token']));
//Write returned XML to file
curl_setopt($ch, CURLOPT_FILE, $fh);
//Execute the curl session
curl_exec($ch);
//Store the curl session info/returned headers into the $info array
$info = curl_getinfo($ch);
//Check if we have been authorised or not
if($info['http_code'] == '401') {
getToken($url);
echo 'Token Failed - getToken() has been run!<br />';
} elseif ($info['http_code'] == '200') {
echo 'Token Worked - Success';
}
//Close the curl session
curl_close($ch);
//Close the open file handle
fclose($fh);
} else {
//Run the getToken function above if we are not authenticated
getToken($url);
}
}
//Connect to the API using connect() function above
connect($request);
?>now I have a not very helpful (imo) pdf which came with this which states
“API Calls
There are six API calls.
• Get Branches – returns a list of all branches
• Get Branch – returns more details for a branch
• Get Property List – returns list of properties for a branch
• Get Property – returns the property details
• Get Changed Properties – returns a list of properties that have changed (updated, added or
deleted) since a certain date and time.
• Get Changed Files – returns a list of files that have changed (updated, added or deleted)
since a certain date and time.
These API calls must all be authenticated.
All the API calls return XML. This XML is defined by a schema. This schema documents the XML
returned.”
and
"How to use the API
This section provides guidance on how you would use the API to initially populate your database and
keep your data in sync, in near to real-time.
Initial Population of your database
- Call ‘Get Branches’ – this returns XML with a list of branches and a URL to the branch details for
each branch.- For each branch in that list, call ‘Get Branch’ and store the branch details in your database. (It
would be useful to store the URL and date and time you queried this branch. Then you can
periodically check this and use the date and time in the ‘If-Modified-Since’ header. If the data
has changed you will get the changed data, otherwise the API will return 304 Not-modified. This
can help you reduce the volume of database updates.)- For each branch in that list, call ‘Get Property List’
- For each property that ‘Get Property List’ returns, call ‘Get Property’ (the URL returned by ‘Get
Property List’) and store the properties locally.- For each property you should download the image(s) and referenced file(s) and store them.
- It would be sensible to allow your system to be able repeat the ‘initial population of your
database’ if you lose sync, or in the event we notify you that this is required due to changes we
have made.
Note 1: How the if-modified-header option works with the properties list differs to the way the
properties changed call works:
When the if-modified-header option is used, the API gets the most recent property changed value
for the client and compares it to the if-modified value. If the if-modified value is earlier, the API
returns all properties; otherwise none.
The Get Changed Properties call only returns properties where the last change for the record is after
the date specified.
User Guide: Client Feed Export (API)
Page 11 of 30
On-going Real-time updates
Periodically you should use the API Calls detailed below to get changed properties and files. To do
this:-- Call ‘Get Changed Properties’ using the date and time you last checked for updates / initially
populated your database.- For each property returned, perform the appropriate operation (get property then update, or
insert or remove the property) to your database.- Store the date and time you checked for updates for the next time you call the API.
- Repeat the same process for files using ‘Get Changed Files’
User Guide: Client Feed Export (API)
Page 12 of 30
API Call List
This section details the list of calls available.
Get Branches
http ://webservices.vebra.com/export/{datafeedid}/v{version}/branch
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
Returns XML with list of branches for the data feed containing
• branch name
• firmid
• branchid
• URL to full branch XML (‘Get Branch’ call)
Please see the schema for full details.
Example URL:
http ://webservices.vebra.com/export/homeestates/v11/branch
(This URL is not active)
Get Branch
http ://webservices.vebra.com/export/{datafeedid}/ v{version}/branch/{clientid}
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
{clientid} is the branch identifier.
This URL is present in the ‘Get Branches’ XML for each branch.
Please see the schema for full details of the XML returned.
Example URL:
http ://webservices.vebra.com/export/ homeestates/v11/branch/1234
(This URL is not active)
User Guide: Client Feed Export (API)
Page 13 of 30
Get Property List
http ://webservices.vebra.com/export/{datafeedid}/ v{version}/branch/{clientid}/property
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
{clientid} is the branch identifier.
Returns XML with the list of properties for the branch specified in the {clientid} containing (for each
property)
• prop_id (the property identifier)
• last changed date and
• URL to full property details XML (‘Get Property’ call).
Please see the schema for full details of the XML returned.
Example URL:
http ://webservices.vebra.com/export/homeestates/v11/branch/1234/property
(This URL is not active)
Note 1: The Get Property List call returns results for current properties only ordered by updated
date. This value is the last time the property, rooms or associated files changed.
User Guide: Client Feed Export (API)
Page 14 of 30
Get Property
http ://webservices.vebra.com/export/{datafeedid}/ v{version}/branch/{clientid}/property/{prop_id}
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
{clientid} is the branch identifier.
{prop_id} is the unique property identifier.
Returns XML with the full property details for the property specified in {prop_id}
Please see the schema for full details of the XML returned.
Example URL:
http ://webservices.vebra.com/export/homeestates/v11/branch/1234/property/12345678
(This URL is not active)
Note 1: The updated value for the files in the Get Property call will return the latest update value we
hold where either the file itself or the media content has changed
Note 2: The Get Property call includes entries for EPC Graphs where the property EPC values are
non-zero and we do not hold associated EPC files for the property record. These file entries are
‘generated’ by the API itself and will not contain the ‘updated’ attribute, nor will they be included in
the Get Changed Files call.
• The individual Energy efficiency chart where the corresponding eecurrent and eepotential
values are greater than 0
• The individual Environmental impact chart where the corresponding eicurrent and
eipotential values are greater than 0
User Guide: Client Feed Export (API)
Page 15 of 30
Get Changed Properties
http ://webservices.vebra.com/export/{datafeedid}/v{version}/property/{yyyy}/{MM}/{dd}/{HH}/{m
m}/{ss}
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
This call expects a date and time after which property changes are returned.
• {yyyy} – year
• {MM} – month with leading zeros
• {dd} – day of the month with leading zeros
• {HH} – the hour of the day (0 – 23) with leading zeros
• {mm} – minutes with leading zeros
• {ss} – seconds with leading zeros
Returns XML with a list of properties for the data feed that have been added, updated or deleted
since the date and time specified, containing (for each property)
• prop_id
• last changed date
• last action on property, and
• URL to full property XML
Valid Values for Last Action on property are:
• updated (this refers to a new property record or an update to an existing property record)
• deleted
Example URL:
http ://webservices.vebra.com/export/homeestates/v11/property/2010/08/31/01/01/01
(This URL is not active)
Note 1: The Get Changed Properties call returns results where the property record or its associated
files or rooms (paragraphs in the xml) have changed with a date/time equal to or greater than the
date / time in the call. It returns results where:- a new property record has been added
- an update to an existing property record has occurred
- an existing property has been deleted
- the associated files have been updated or deleted
User Guide: Client Feed Export (API)
Page 16 of 30- the associated rooms (paragraphs) have been updated or deleted
- Additionally, if the Branch’s Lettings Fee data has been updated, in this case, all properties will
be returned for the Branch with the lastchanged date being the latest of the above changes and
not the date the Lettings Fee data was added or updated
The lastchanged value in the returned results will always be the latest of all changes the call takes
into consideration.
Note 2: The Get Changed Properties call returns results for current property records (last action =
update) where a new property record has been added or is an update to an existing property record;
or a deletion of an existing property record (last action = deleted).
User Guide: Client Feed Export (API)
Page 17 of 30
Get Changed Files
http ://webservices.vebra.com/export/{datafeedid}/v{version}/
files/{yyyy}/{MM}/{dd}/{HH}/{mm}/{ss}
{datafeedid} is the identifier for this data feed.
{version} the current version is 11.
This call expects a date and time after which property changes are returned.
• {yyyy} – year
• {MM} – month with leading zeros
• {dd} – day of the month with leading zeros
• {HH} – the hour of the day (0 – 23) with leading zeros
• {mm} – minutes with leading zeros
• {ss} – seconds with leading zeros
Returns XML with list of changed files for the feed containing
• file element with file_id
• file element with file_propid,
• last changed date
• a flag to denote if the file was deleted. If false, it was either added or updated.
• URL to full property XML (‘Get Property’ call)
• URL of the file.
Example URL:
http ://webservices.vebra.com/export/homeestates/v11/files/2010/08/31/14/23/01
(This URL is not active)
Note 1: Deleted files are supported in this version of the API and the Get Changed Files call returns
both current and deleted files. The node in the xml returns a value of “false” for current
files and “true” for deleted files.
Note 2: The Get Changed Files call includes the File Id of the changed files. When combined with the
file_propid, this is the unique identifier for this file, allowing matching against previously
downloaded files."