Web API Reference (Legacy) - Revision history

Demitri at 02:00, 2 May 2014

2014-05-02T02:00:45Z

Demitri at 00:49, 2 May 2014

2014-05-02T00:49:40Z

Demitri at 00:49, 2 May 2014

2014-05-02T00:49:21Z

Demitri at 00:48, 2 May 2014

2014-05-02T00:48:57Z

Demitri: Demitri moved page Web API Reference to Web API Reference (Legacy): This reference guide is for the legacy web API

2014-05-02T00:47:19Z

Demitri moved page Web API Reference to Web API Reference (Legacy): This reference guide is for the legacy web API

Demitri at 22:19, 21 April 2014

2014-04-21T22:19:33Z

Demitri: Demitri moved page Remote API to Web API Reference: More distinct, descriptive title

2014-04-21T21:55:14Z

Demitri moved page Remote API to Web API Reference: More distinct, descriptive title

Demitri at 23:49, 6 February 2014

2014-02-06T23:49:39Z

Demitri: /* Tagging Records */

2014-01-03T19:18:08Z

‎Tagging Records

Demitri: /* Tagging Records */

2014-01-03T19:17:48Z

‎Tagging Records

@@ Line 2: / Line 2: @@
 '''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in the app, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the [[REST API Reference]] page.
-X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.
+X2Engine features a HTTP-based API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot 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 <tt>user</tt> and <tt>userKey</tt>, 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 <tt>authUser</tt> and <tt>authPassword</tt>, and authPassword is the password hash.

@@ Line 1: / Line 1: @@
 [[Category:Development]]
-'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in service, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the [[REST API Reference]] page.
+'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in the app, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the [[REST API Reference]] page.
 X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.

@@ Line 1: / Line 1: @@
 [[Category:Development]]
-'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in service, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see [[REST API]]
+'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in service, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the [[REST API Reference]] page.
 X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.

← Older revision		Revision as of 00:48, 2 May 2014
Line 1:		Line 1:
	[[Category:Development]]		[[Category:Development]]
		+	'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in service, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see [[REST API]]

	X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController\|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.		X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController\|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.

← Older revision		Revision as of 22:19, 21 April 2014
Line 235:		Line 235:
	== Get a list of all users in the app ==		== Get a list of all users in the app ==
	The method [[x2propdoc:ApiController.html#_actionListUsers\|actionListUsers()]] (accessed via GET at /api/listUsers) requires authentication (as query parameters) and will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action. It returns, upon success, a JSON-encoded list of users, each user a list of attribute name to attribute value key/value pairs (according to the columns of the <tt>x2_users</tt> table. The <tt>password</tt> and <tt>userKey</tt> fields, however, are ommitted from the attributes of all users.		The method [[x2propdoc:ApiController.html#_actionListUsers\|actionListUsers()]] (accessed via GET at /api/listUsers) requires authentication (as query parameters) and will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action. It returns, upon success, a JSON-encoded list of users, each user a list of attribute name to attribute value key/value pairs (according to the columns of the <tt>x2_users</tt> table. The <tt>password</tt> and <tt>userKey</tt> fields, however, are ommitted from the attributes of all users.
		+
		+	= Security Considerations =
		+	It is in general considered a best practice to securely encrypt web traffic to your web server with HTTP over SSL (HTTPS). Without this, API authentication credentials will be sent directly to the server in plain text, and thus vulnerable to exposure via man-in-the-middle (MITM) attacks and packet sniffing. Note, however, that if HTTPS is not used on the server, normal web-browser authentication would also be vulnerable to this kind of attack anyway, because the session ID stored in the cookie can similarly be stolen and used to access the system as any given user.
		+
		+	If SSL-protected HTTP is not an option due to the cost, it is thus recommended that you keep all of your API requests within the same server or intranet and/or behind a firewall, as that would mean that both the origin and target of the API web request would be within a protected network area, and thus would more difficult to access.

← Older revision	Revision as of 00:47, 2 May 2014
(No difference)

← Older revision	Revision as of 21:55, 21 April 2014
(No difference)

@@ Line 1: / Line 1: @@
 [[Category:Development]]
-X2CRM features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.
+X2Engine features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|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 [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot 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 <tt>user</tt> and <tt>userKey</tt>, 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 <tt>authUser</tt> and <tt>authPassword</tt>, and authPassword is the password hash.
@@ Line 116: / Line 116: @@
 == 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: <tt>index.php/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:
+One can create, get lists of and delete relationships between records in X2Engine 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>index.php/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"
 |-
@@ Line 227: / Line 227: @@
 == Inbound VoIP call notifications ==
-PBX systems that are connected to the internet, especially if they are based on [[wiki:Asterisk_(PBX)|Asterisk]], will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2CRM. The action api/voip, which does not require authentication, is the most basic way of doing so where all that is necessary is to notify sales reps when a contact is calling. This gives the rep a window of few seconds (depending on the dialplan, and if the caller is typing in someone's extension directly) to get ready to receive the call when it finally reaches them. It creates notifications for all users (if assigned to "Anyone"), an activity feed event, and if the contact is assigned to someone, it opens a new window with the record on screen in that rep's web browser.
+PBX systems that are connected to the internet, especially if they are based on [[wiki:Asterisk_(PBX)|Asterisk]], will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2Engine. The action api/voip, which does not require authentication, is the most basic way of doing so where all that is necessary is to notify sales reps when a contact is calling. This gives the rep a window of few seconds (depending on the dialplan, and if the caller is typing in someone's extension directly) to get ready to receive the call when it finally reaches them. It creates notifications for all users (if assigned to "Anyone"), an activity feed event, and if the contact is assigned to someone, it opens a new window with the record on screen in that rep's web browser.
 To use it, make a GET request to index.php/api/voip/data/{phone number}, where {phone number} is the caller ID (without spaces, parentheses or dashes) calling in. Note, it may yield better results if the country code is ommitted; the search for contacts is based on serialized phone numbers but also returns the first partial match. So, as long as the <tt>data</tt> parameter is a unique part of a phone number, it won't match the incorrect contact record.

@@ Line 209: / Line 209: @@
 : Parameter missing
 ;404
-: No tags were deleted; the model did not have specified tags
+: No tags were deleted; the model did not have specified tags (or, model not found)
+|
 ;message

@@ Line 179: / Line 179: @@
 : Tags applied
 ;400
-: Required parameter is missing
+: Required parameter is missing, or invalid model
 ;500
 : Failed to add tags for some reason, i.e. database error
@@ Line 190: / Line 192: @@
 |Get tags on a model
 |<tt>GET</tt>, with the model class and id specified in the query parameters as when updating a model (see the previous section, on CRUD methods).
-|Always responds with code 200 unless authentication fails or an invalid model is specified
 |A JSON-encoded list of tags
 |-