© 2015 X2Engine Inc.

Difference between revisions of "Web API Reference (Legacy)"

From X2Engine
Jump to: navigation, search
(→‎Create a relationship between two records)
(→‎Create a relationship between two records)
Line 112: Line 112:
 
= Miscellaneous API actions =
 
= Miscellaneous API actions =
  
−
== Create a relationship between two records ==
+
== Managing relationships betweeen records ==
−
One can create, get lists of and delete relationships between records in X2CRM by using the [[x2propdoc:ApiController.html#_actionRelationship|actionRelationship()]] method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL. This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:
+
One can create, get lists of and delete relationships between records in X2CRM by using the [[x2propdoc:ApiController.html#_actionRelationship|actionRelationship()]] method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL: <tt>/api/relationship/model/Contacts</tt> (for relating to models of class <tt>Contacts</tt>). This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:
−
{|class="wikitable" align="center"
+
{|class="wikitable"
 
|-
 
|-
 
! scope="col" | Use
 
! scope="col" | Use
−
! scope="col" | Request Type / Data
+
! scope="col" | Request type/data expected
 
! scope="col" | Codes
 
! scope="col" | Codes
 
! scope="col" | Response
 
! scope="col" | Response
 
|-
 
|-
 +
|Create a relationship
 +
|<tt>POST</tt> with url-encoded form data: <tt>secondType</tt> (model class of target), <tt>firstId</tt> (id of the first model), and <tt>secondId</tt> (id of the target model), in addition to authentication parameters.
 
|
 
|
 +
;200
 +
: The relationship was created successfully or already exists
 +
;400
 +
: The relationship failed validation (most likely because the target model records do not exist)
 +
;500
 +
: Failed to insert relationship record for some other reason, i.e. database error
 
|
 
|
 +
;error
 +
: false/true based on whether the relation was inserted
 +
;message
 +
: String; message telling whether the relationship exists or not, or if there was an error
 +
|-
 +
|Get relationships between two models
 +
|<tt>GET</tt>, with query parameters same as those in creating relationships, and authentication. However, parameters may be omitted to make the query more inclusive, i.e. omitting <tt>secondId</tt> but setting <tt>firstId</tt> to 5, <tt>model</tt> to "Accounts" and <tt>secondType</tt> to "Contacts" will show all relationships between the Account record with id=5 and contact records.
 
|
 
|
 +
;200
 +
: Relationships exist
 +
;404
 +
: No relationships found
 +
|A list (JSON-encoded, of course) of relationship records (each itself an attribute -> value pair list)
 +
|-
 +
|Delete a relationship
 +
|<tt>DELETE<tt>, with everything defined in the query parameters. Behavior is similar to the <tt>GET</tt> method; in fact, it can delete multiple relationships at the same time, similarly omitting parameters to make the query more inclusive.
 
|
 
|
−
|-
+
;200
 +
: Relationship(s) successfully deleted
 +
;404
 +
: No relationships found were deleted
 +
;500
 +
: Some relationship(s) could not be deleted due to a database error
 
|}
 
|}
  
Line 133: Line 161:
  
  
−
{|class="wikitable" align="center"
+
{|class="wikitable"
 
|-
 
|-
 
! scope="col" | Use
 
! scope="col" | Use

Revision as of 00:34, 7 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/.

Authenticating

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. In versions earlier than 2.9.1, these parameters are named authUser and authPassword, and authPassword is the password hash. A user's API key can be set by the administrator in the User module by visiting the update page for the given user.

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; authentication data
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

Attribute Input Format

The input to the API will be processed in the same way that it is within the application, that is to say, using the method X2Model.setX2Fields(). In particular, the method Fields.parseValue() is used for processing and transforming the data before it is recorded in the database. The case statement in that method shows how each type of field is processed (see X2Model and Dynamic Fields for more information on field types and how fields are dynamically managed)

Miscellaneous API actions

Managing relationships betweeen records

One can create, get lists of and delete relationships between records in X2CRM by using the actionRelationship() method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL: /api/relationship/model/Contacts (for relating to models of class Contacts). This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:

Use Request type/data expected Codes Response
Create a relationship POST with url-encoded form data: secondType (model class of target), firstId (id of the first model), and secondId (id of the target model), in addition to authentication parameters.
200
The relationship was created successfully or already exists
400
The relationship failed validation (most likely because the target model records do not exist)
500
Failed to insert relationship record for some other reason, i.e. database error
error
false/true based on whether the relation was inserted
message
String; message telling whether the relationship exists or not, or if there was an error
Get relationships between two models GET, with query parameters same as those in creating relationships, and authentication. However, parameters may be omitted to make the query more inclusive, i.e. omitting secondId but setting firstId to 5, model to "Accounts" and secondType to "Contacts" will show all relationships between the Account record with id=5 and contact records.
200
Relationships exist
404
No relationships found
 A list (JSON-encoded, of course) of relationship records (each itself an attribute -> value pair list)
Delete a relationship DELETE<tt>, with everything defined in the query parameters. Behavior is similar to the <tt>GET method; in fact, it can delete multiple relationships at the same time, similarly omitting parameters to make the query more inclusive.
200
Relationship(s) successfully deleted
404
No relationships found were deleted
500
Some relationship(s) could not be deleted due to a database error


actionVoip()


Use Method Relative URL Authentication Notes
Make note of a VoIP call actionVoip() /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.
Get a list of all users in the app actionListUsers() /listUsers yes Will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action.

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)

Retrieved from "http://wiki.x2crm.com/index.php?title=Web_API_Reference_(Legacy)&oldid=1053"