PHP file to connect to vebra api, need help with api calls

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 :upside_down_face: .

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

  1. Call ‘Get Branches’ – this returns XML with a list of branches and a URL to the branch details for
    each branch.
  2. 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.)
  3. For each branch in that list, call ‘Get Property List’
  4. For each property that ‘Get Property List’ returns, call ‘Get Property’ (the URL returned by ‘Get
    Property List’) and store the properties locally.
  5. For each property you should download the image(s) and referenced file(s) and store them.
  6. 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:-
  7. Call ‘Get Changed Properties’ using the date and time you last checked for updates / initially
    populated your database.
  8. For each property returned, perform the appropriate operation (get property then update, or
    insert or remove the property) to your database.
  9. Store the date and time you checked for updates for the next time you call the API.
  10. 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:
  11. a new property record has been added
  12. an update to an existing property record has occurred
  13. an existing property has been deleted
  14. the associated files have been updated or deleted
    User Guide: Client Feed Export (API)
    Page 16 of 30
  15. the associated rooms (paragraphs) have been updated or deleted
  16. 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."
Sponsor our Newsletter | Privacy Policy | Terms of Service