Introduction
All API calls to the PYXI Core Engine are made by passing in data in JSON syntax.
Most responses are received in JSON syntax, with a few exceptions e.g. the response to getting a file is to receive the file contents as a binary stream, not as JSON.
The URL to which all requests should be made is:
https://12345678.mypyxi.com/api
where 12345678 is your PYXI account number.
See sample PHP code below for example minimal code to manage API calls.
Making a Request
All requests include the following standard items:
- account – the PYXI account ID. This is generated and provided by the account set-up API call discussed later
- apikey – the unique key assigned to a particular DataSource (i.e. communicating application) set-up on this account.
If you have not already done so, create a DataSource record named for the application from which you will make API calls. You
will find an API key generated on that DataSource record.
- action – one of the available actions, discussed in the following sections
Depending on the action, additional information is almost always required.
Specifying a Single Record
For actions that are to be performed on a single record, the record can be specified in multiple ways
- By Record Url – if the url of a record is known, it can be provided as a single parameter in recordurl
- By Record Number – specify the record type in recordtype and the record id in recordid
- By Filter – specify the record type in recordtype and provide a filter condition in filter. The first record matching the filter condition will be used.
Specifying a List of Records
To specify a list of records, use some or all of the following:
- recordtype – the record type of the records to be listed. This is required.
- filter – optional filter condition. Only records matching the filter condition will be included
- sortby – optional name of method by which records should be sorted
- sortorder – optionally specify ‘desc’ to have records sorted in descending order, otherwise default is ascending order
- start – optionally specify the starting record number – usually used to enquire on ‘paged’ lists of records
- limit – optionally specify the maximum number of records to be included – usually used to enquire on paged lists of records
Standard Response Structures
Individual Record
An individual record response contains, at minimum, the following:
- recordurl – the unique record url string containing the record type and record id
- recordid – the unique numeric record id
- recordtype – the string type of the record
- name – the display name of the record (e.g. for a Person, this is “FirstName LastName”)
If specific values have been requested, these are returned in a ‘values’ array. Note that a value response may be a discrete value or a Record List
Record List
A list of records is returned as an array containing the following:
- recordtype– the string type of the records in the list
- count – the number of records returned in this response
- total – the total number of records that match the list criteria. This can be higher than total if the list response has been restricted with a limit value
- records – an array of individual record responses
PHP Code
The code below provides a bare minimum class for making API calls to PYXI. It only assumes that the API Key and Account ID are available in environment variables –
modify the code based on wherever you store such variables. You will doubtless want to expand this class with additional error-handling and/or to provide
wrapper methods to individual API actions.
Sample PYXI API Class
class PyxiAPI {
public static function call($aPostData) {
// Modify based on how/where you store the API Key and Account ID
$aPostData['apikey'] = getenv('PYXI_API_KEY');
$sUrl = sprintf('https://%s.mypyxi.com/api', getenv('PYXI_ACCOUNT_ID'));
return self::curl($sUrl, $aPostData);
}
public static function curl($sUrl, $aPostData) {
$hCurl = curl_init();
curl_setopt($hCurl, CURLOPT_URL, $sUrl);
curl_setopt($hCurl, CURLOPT_CONNECTTIMEOUT, 0);
// Set new cookie session
curl_setopt($hCurl, CURLOPT_COOKIESESSION, true);
// Return, rather than output, the result
curl_setopt($hCurl, CURLOPT_RETURNTRANSFER, true);
// Follow any Location redirects
curl_setopt($hCurl, CURLOPT_FOLLOWLOCATION, true);
// Don't do SSL certificate checking
curl_setopt($hCurl, CURLOPT_SSL_VERIFYPEER, false);
// Set post variables
curl_setopt($hCurl, CURLOPT_POST, true);
curl_setopt($hCurl, CURLOPT_POSTFIELDS, json_encode($aPostData));
// Set Headers
$sContentType = 'application/json';
$aHttpHeaders = array(
sprintf('Content-Type: %s', $sContentType),
sprintf('Accept: %s', $sContentType)
);
curl_setopt($hCurl, CURLOPT_HTTPHEADER, $aHttpHeaders);
// Call it
$sResponse = curl_exec($hCurl);
//$nHttpCode = curl_getinfo($hCurl, CURLINFO_RESPONSE_CODE);
curl_close($hCurl);
return $sResponse;
}
}
Sample Call
$aPostData = array(
'action' => 'list',
'recordtype' => 'person'
);
$oResponse = json_decode(PyxiAPI::call($aPostData));
foreach ($oResponse->records as $oPerson) {
…
}