© 2015 X2Engine Inc.
Difference between revisions of "Web API Reference (Legacy)"
(→API request URL formatting) |
(→API request URL formatting) |
||
| Line 30: | Line 30: | ||
! scope="col" | Method | ! scope="col" | Method | ||
! scope="col" | URL | ! scope="col" | URL | ||
| + | ! scope="col" | ID required | ||
! scope="col" | Usage | ! scope="col" | Usage | ||
|- | |- | ||
| − | |actionCreate</tt> | + | |[[x2propdoc:ApiController.html#_actionCreate|actionCreate()]] |
| − | | | + | |<tt>index.php/api/create</tt> |
| − | | | + | |no |
| + | |Creates a new record | ||
|- | |- | ||
| − | |<tt> | + | |[[x2propdoc:ApiController.html#_actionLookup|actionLookup()]] |
| − | | | + | |<tt>index.php/api/lookup</tt> |
| − | | | + | |no |
| + | |Searches for a record. | ||
|- | |- | ||
| − | |<tt> | + | |[[x2propdoc:ApiController.html#_actionView|actionView()]] |
| − | | | + | |<tt>index.php/api/view</tt> |
| − | | | + | |yes |
| + | |Views a record by its numeric ID | ||
|- | |- | ||
| − | |<tt> | + | |[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate]] |
| − | | | + | |<tt>index.php/api/update</tt> |
| − | | | + | |yes |
| + | |Update a record by numeric ID | ||
|- | |- | ||
| − | | | + | |[[x2propdoc:ApiController.html#_actionDelete|actionDelete]] |
| − | | | + | |<tt>index.php/api/delete</tt> |
| + | |yes | ||
| | | | ||
|- | |- | ||
|} | |} | ||
| + | , respectively. Per the [[yiiguide:basics.convention#url|URL and route conventions]], these | ||
Revision as of 18:57, 19 September 2012
Contents
Introduction
X2EngineCRM 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/.
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 X2EngineCRM 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.
Manual Configuration
For users who installed at versions earlier than 1.6.6 and have upgraded, the following steps must be taken to use the remote API:
- Log in as admin
- Create a new user with username "api", and make sure its status is set to "inactive".
- Make note of the password that you enter for this user, and obtain the MD5 digest of it by one of the following means:
- Use a third-party hash generation 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.
- Log into the database and obtain the generated password hash from the entry in table x2_users (i.e. by navigating to it in PHPMyAdmin), or run
SELECT `password` FROM `x2_users` WHERE `username`='api'
- If you have the PHP command line interface installed on your computer, obtain it with the command: echo md5("password")."\n";
With a dedicated user for API authentication and access, it should be ready to use.
API request URL formatting
(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 | URL | ID required | Usage |
|---|---|---|---|
| actionCreate() | index.php/api/create | no | Creates a new record |
| actionLookup() | index.php/api/lookup | no | Searches for a record. |
| actionView() | index.php/api/view | yes | Views a record by its numeric ID |
| actionUpdate | index.php/api/update | yes | Update a record by numeric ID |
| actionDelete | index.php/api/delete | yes |
, respectively. Per the URL and route conventions, these
