© 2015 X2Engine Inc.

Web API Reference (Legacy)

From X2Engine
Revision as of 23:46, 6 September 2013 by Demitri (talk | contribs) (CRUD (Create, Read, Update & Delete) API Methods)
Jump to: navigation, search


X2CRM features a remote API for inserting, updating, querying and deleting records via ApiController, which (with few exceptions) responds in JSON format. The API can perform these operations with any subclass of X2Model. URLs (after the domain name and relative path to the document root) for web requests to the API begin with index.php/api/. In most calls to the API, authentication is required in the form of GET or POST parameters user and userKey, which are the username and API key (respectively) of a user in the CRM.

API Response

In the case of an error, the API will still respond in JSON format, and will set the HTTP response code according to the following rules


CRUD (Create, Read, Update & Delete) API Methods

The following API actions can be used with any subclass of X2Model (i.e. Contacts, Accounts, Opportunity, etc.) In the following reference table, the model class to be used for display purposes is Contacts, and the id (primary key) value is 5.

Use Method URL Authentication Request type/data expected Code Response properties
Create a new record actionCreate() /create/model/Contacts With post data POST; authentication & model attributes together in a flat list as URL-encoded form data
200
Record successfully inserted
500
Model failed validation
error
true if and only if the new record was created successfully
model
attributes of the model as key-value pairs (indexed by attribute name)
modelErrors
validation errors for each attribute, if applicable
Search for the first record matching one or more fields actionLookup() /lookup/model/Contacts With post data POST; Same as with the create action
200
found record
404
no record found
If successful: attributes of the model as a flat key-value pair list (indexed by attribute name). Otherwise:
error
boolean / true
message
"No item found with specified attributes."
Retrieve a record by primary key actionView() /view/Contacts/id/5 As additional query parameters appended to the URL GET
200
Record found with specified primary key
400
The primary key is not included properly or specified
404
No record found
Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
error
boolean / true, indicating an error
message
A string containing an explanation of what went wrong
Update a preexisting record actionUpdate() /update/model/Contacts/id/5 With post data POST; same as with create method
200
Record successfully updated
404
Record to be updated does not exist
400
Primary key is missing from query parameters
500
Model failed validation during update
Same as with create action
Delete a record actionDelete() /delete/model/Contacts/id/5 With post data POST
200
Record successfully deleted
404
Record to be deleted does not exist
400
Primary key is missing from query parameters
500
Record could not be deleted
message
"1" if successful; else, an error message
error
boolean / true if and only if successful


The post data variables should be named according to the column names of the model for which the API being called. When making API calls, the same validation rules as in normal use of the app also apply. In the case that the input does not pass validation, the API will respond with the validation errors.

Authenticating

Using the API requires authentication credentials for the web application in the form of two post data fields: user and userKey, containing the username and API key of that user (versions 2.9.1 and later), or authUser and authPassword, containing the username and password hash (versions earlier than 2.9.1), respectively. A user's API key can be set by the administrator in the User module by visiting the update page for the given user.

Available API functions

(See also the documentation on ApiController)

The methods of ApiController used for creating, querying, viewing (by ID), updating and deleting records are:

Method Base URL ID required Usage
actionCreate() index.php/api/create no Creates a new record
actionLookup() index.php/api/lookup no Searches for a record based on one or more fields
actionView() index.php/api/view yes Views a record
actionUpdate() index.php/api/update yes Updates a record
actionDelete() index.php/api/delete yes Deletes a record
actionVoip() index.php/api/voip no Notifies the assignee of a contact having called (if the phone number matches).
Requires only the "phone" field, as a GET parameter, it being a 10+ digit phone number.

Specifying Model

The API requires specifying the model for which the transaction will be performed as a GET parameter with key "model", with actionVoip being the only current exception. Per the URL format rule of X2CRM, which is "path" (see CUrlManager for more information), the full URL of the request will be: index.php/api/[method]/model/[model name]. So, for example, an API call to create a new contact record should use index.php/api/create/model/Contacts

Usage Example

The file leadCapture.php in the web root of the codebase contains a few noteworthy examples of API calls. Of particular significance is the necessity of creating a contact first and then using lookup to obtain its numeric ID in order to create an action associated with that contact.

(section in progress)