© 2015 X2Engine Inc.
Difference between revisions of "Web API Reference (Legacy)"
(→Usage) |
(→Usage) |
||
| Line 9: | Line 9: | ||
= Usage = | = Usage = | ||
In the reference table here, the model class to be used is <tt>Contacts</tt>. | In the reference table here, the model class to be used is <tt>Contacts</tt>. | ||
| − | {|class="wikitable" align="left | + | {|class="wikitable" align="left" |
|- | |- | ||
! scope="col" | Usage | ! scope="col" | Usage | ||
| Line 15: | Line 15: | ||
! scope="col" | URL | ! scope="col" | URL | ||
! scope="col" | Authentication | ! scope="col" | Authentication | ||
| − | |||
! scope="col" | Request type(s) | ! scope="col" | Request type(s) | ||
| − | ! scope="col" | Expected data | + | ! scope="col" | Expected data |
! scope="col" | Code | ! scope="col" | Code | ||
! scope="col" | Response properties | ! scope="col" | Response properties | ||
| Line 25: | Line 24: | ||
|<tt>index.php/api/create/model/Contacts</tt> | |<tt>index.php/api/create/model/Contacts</tt> | ||
|With post data | |With post data | ||
| − | |||
|<tt>POST</tt> | |<tt>POST</tt> | ||
|Form (post) data containing authentication and attributes (key-value) of the model to be created, together, as a flat list | |Form (post) data containing authentication and attributes (key-value) of the model to be created, together, as a flat list | ||
| Line 41: | Line 39: | ||
|<tt>index.php/api/lookup/model/Contacts</tt> | |<tt>index.php/api/lookup/model/Contacts</tt> | ||
|With post data | |With post data | ||
| − | |||
|<tt>POST</tt> | |<tt>POST</tt> | ||
|Similar to the <tt>create</tt> action | |Similar to the <tt>create</tt> action | ||
| Line 47: | Line 44: | ||
|If successful: attributes of the model as a flat list (indexed by attribute name) key-value pairs indexed by name. Otherwise: <tt>{"error":true,"message":"No item found with specified attributes."}</tt> | |If successful: attributes of the model as a flat list (indexed by attribute name) key-value pairs indexed by name. Otherwise: <tt>{"error":true,"message":"No item found with specified attributes."}</tt> | ||
|- | |- | ||
| − | |Retrieve a record based on its primary key | + | |Retrieve a record based on its primary key ('''5''', for instance) |
|[[x2propdoc:ApiController.html#_actionView|actionView()]] | |[[x2propdoc:ApiController.html#_actionView|actionView()]] | ||
| − | |<tt>index.php/api/view</tt> | + | |<tt>index.php/api/view/Contacts/id/5</tt> |
| + | |As query parameters, i.e. <tt>index.php/api/view/Contacts/id/5?user=yourusername&userKey=Y0URU53RK3Y</tt> | ||
| + | |<tt>GET</tt> | ||
| + | |200 if successful, else 404 if no record found, else 400 if the primary key is not included properly or specified | ||
| + | |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 | ||
|- | |- | ||
|[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate()]] | |[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate()]] | ||
Revision as of 22:55, 6 September 2013
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.
Contents
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
Usage
In the reference table here, the model class to be used is Contacts.
| Usage | Method | URL | Authentication | Request type(s) | Expected data | Code | Response properties |
|---|---|---|---|---|---|---|---|
| Create a new record | actionCreate() | index.php/api/create/model/Contacts | With post data | POST | Form (post) data containing authentication and attributes (key-value) of the model to be created, together, as a flat list | 200 if successful, else 500 |
|
| Search for the first record matching one or more fields | actionLookup() | index.php/api/lookup/model/Contacts | With post data | POST | Similar to the create action | 200 if successful, else 404 | If successful: attributes of the model as a flat list (indexed by attribute name) key-value pairs indexed by name. Otherwise: {"error":true,"message":"No item found with specified attributes."} |
| Retrieve a record based on its primary key (5, for instance) | actionView() | index.php/api/view/Contacts/id/5 | As query parameters, i.e. index.php/api/view/Contacts/id/5?user=yourusername&userKey=Y0URU53RK3Y | GET | 200 if successful, else 404 if no record found, else 400 if the primary key is not included properly or specified | Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
| |
| 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. |
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)
