© 2015 X2Engine Inc.
Difference between revisions of "Web API Reference (Legacy)"
(→Manual Configuration) |
|||
| Line 64: | Line 64: | ||
= Manual Configuration = | = Manual Configuration = | ||
| − | + | During installation, the remote API is configured automatically. However, for installations that have been updated from earlier, the following steps must be taken to configure the remote API: | |
| − | # Log | + | |
| + | == After updating to a version before 2.7 from a version before 1.6.1 == | ||
| + | # Log into X2CRM as admin | ||
# Create a new user with username "api", and make sure its status is set to "inactive". Then, perform one of the following: | # Create a new user with username "api", and make sure its status is set to "inactive". Then, perform one of the following: | ||
| − | #* Make note of the password entered for the user and obtain its md5 hash using a third-party tool. We recommend [http://www.miraclesalad.com/webtools/md5.php this one], because the string to be hashed is not submitted to any remote server, but is calculated with client-side javascript. Alternately, if you have the PHP command line interface installed on your computer, obtain it with the command: <tt>echo md5("</tt>''password''<tt>")."\n";</tt> | + | #* Make note of the password entered for the user and obtain its md5 hash using a third-party tool. We recommend [http://www.miraclesalad.com/webtools/md5.php this one], because the string to be hashed is not submitted to any remote server, but is calculated with client-side javascript. Alternately, if you have the PHP command line interface installed on your computer, obtain it with the command: <tt>echo md5("</tt>''password''<tt>")."\n";</tt> |
#* If you can access your database directly (i.e. via PHPMyAdmin), log into it and manually set the password field in table x2_users, i.e. <syntaxhighlight lang="mysql">UPDATE `x2_users` SET `password`='<password>' WHERE `username`='api'</syntaxhighlight> | #* If you can access your database directly (i.e. via PHPMyAdmin), log into it and manually set the password field in table x2_users, i.e. <syntaxhighlight lang="mysql">UPDATE `x2_users` SET `password`='<password>' WHERE `username`='api'</syntaxhighlight> | ||
| − | # Use the password hash or manually-set password to authenticate in API requests. | + | # Use the password hash or manually-set password to authenticate in API requests. In the post data sent to the API action, the post field <tt>authUser</tt> should be "api" and "authPassword" should be the password hash (or, if you inserted manually, the password entered verbatim). |
| + | |||
| + | == After updating to 2.7 - 2.7.1 from a version before 2.7 == | ||
| + | Log into the database and set the <tt>userKey</tt> field on the desired record in x2_users, OR: log into X2CRM as an administrator, go into the ''Users'' module and update the desired user; a key will be randomly generated. Then, query the userKey field on the user's record in the database. In post data sent to the API action, there should be a <tt>user</tt> field set to the <tt>username</tt> of the user as who the API request will be executed, and a <tt>userKey</tt> field with the same value as is recorded in the database. | ||
Revision as of 20:05, 31 January 2013
X2CRM features a remote API for inserting, updating, querying and deleting records. The API is accessed via POST requests to the API controller (see: ApiController) and thus, URLs (after the domain name and relative path to the document root) for calls to the API will begin with index.php/api/. Instances of X2CRM that were installed at version 1.6.6 and later should have this feature configured and ready for use; users who have upgraded from earlier versions should follow the instructions in Manual Configuration
Contents
Usage
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 authUser and authPassword, which contain the username of a user in the web application and the md5 hash of its password, respectively. Users who have installed X2CRM at version 1.6.6 or later should have a user named "api" in their web application, created during the installation process and given a random password. The authentication details should be stored in webLeadConfig.php in the web root.
With a dedicated user for API authentication and access, and it should then be ready to use.
Available API functions
(See also the documentation on x2doc:ApiController)
The methods of x2doc: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)
Manual Configuration
During installation, the remote API is configured automatically. However, for installations that have been updated from earlier, the following steps must be taken to configure the remote API:
After updating to a version before 2.7 from a version before 1.6.1
- Log into X2CRM as admin
- Create a new user with username "api", and make sure its status is set to "inactive". Then, perform one of the following:
- Make note of the password entered for the user and obtain its md5 hash using a third-party tool. We recommend this one, because the string to be hashed is not submitted to any remote server, but is calculated with client-side javascript. Alternately, if you have the PHP command line interface installed on your computer, obtain it with the command: echo md5("password")."\n";
- If you can access your database directly (i.e. via PHPMyAdmin), log into it and manually set the password field in table x2_users, i.e.
UPDATE `x2_users` SET `password`='<password>' WHERE `username`='api'
- Use the password hash or manually-set password to authenticate in API requests. In the post data sent to the API action, the post field authUser should be "api" and "authPassword" should be the password hash (or, if you inserted manually, the password entered verbatim).
After updating to 2.7 - 2.7.1 from a version before 2.7
Log into the database and set the userKey field on the desired record in x2_users, OR: log into X2CRM as an administrator, go into the Users module and update the desired user; a key will be randomly generated. Then, query the userKey field on the user's record in the database. In post data sent to the API action, there should be a user field set to the username of the user as who the API request will be executed, and a userKey field with the same value as is recorded in the database.
