API – Introduction to PYXI API

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://mypyxi.com/api

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'); $aPostData['account'] = getenv('PYXI_ACCOUNT_ID'); return self::curl('https://mypyxi.com/api', $aPostData); } public static function curl($sUrl, $aPostData) { $hCurl = curl_init(); curl_setopt($hCurl, CURLOPT_URL, $sUrl); curl_setopt($hCurl, CURLOPT_CONNECTTIMEOUT, 0); $aCleanedPostData = array(); foreach ($aPostData as $sKey => $xValue) { if (is_array($xValue)) { $xValue = json_encode($xValue, JSON_UNESCAPED_SLASHES); } $aCleanedPostData[$sKey] = $xValue; } // Set new cookie session curl_setopt($hCurl, CURLOPT_COOKIESESSION, true); // Return, rather than output, the result curl_setopt($hCurl, CURLOPT_RETURNTRANSFER, 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, $aCleanedPostData); $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) { … }

    Get Started