© 2015 X2Engine Inc.
Difference between revisions of "REST API Reference"
(→Creating Web Hooks) |
(→Creating Web Hooks) |
||
Line 408: | Line 408: | ||
== Creating Web Hooks == | == Creating Web Hooks == | ||
− | To create a hook with an event that depends on a model type (i.e. contact updated vs. account updated), send a JSON-encoded list of hook attributes via < | + | To create a hook with an event that depends on a model type (i.e. contact updated vs. account updated), send a JSON-encoded list of hook attributes via <tt>POST</tt> to the following URI: |
index.php/api2/{_class}/hooks | index.php/api2/{_class}/hooks | ||
− | Or, to create a web hook associated with a generic event (that does not depend on model type): | + | Or, to create a web hook associated with a generic event (that does not depend on model type), or a model of determined/unambiguous type (i.e. "Action Complete"): |
index.php/api2/hooks | index.php/api2/hooks | ||
− | The POST-ed JSON-encoded dictionary should contain at least the following properties: <tt> | + | The POST-ed JSON-encoded dictionary should contain at least the following properties: |
+ | |||
+ | {|class="wikitable" | ||
+ | |- | ||
+ | ! scope="row" | <tt>event</tt> | An event name; see [[#Supported Event Names and X2Flow]] | ||
+ | ! scope="row" | <tt>target_url</tt> | The remote URL to receive the payload | ||
+ | ! scope="row" | <tt>directPayload</tt> | (optional): a 1 or 0 (or true/false). See [[#Interpreting Payload Data]] for more information on this option | ||
== Supported Event Names and X2Flow == | == Supported Event Names and X2Flow == |
Revision as of 22:31, 23 May 2014
X2Engine's second-generation HTTP-based API, available as of version 4.1, is (for the most part) REST-ful, and includes many improvements over the original API.
Introduction
This API within X2Engine, can be accessed via the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2
It also:
- Exclusively uses JSON for data input and output
- Tends to use similar URIs for both input and output (distinguishing operations via the request method)
- Uses a variety of server response codes to distinguish error scenarios in the case of an unsuccessful transaction
- Uses the "HTTP Basic Auth" method for authentication
For example, to create a contact, one would send a POST request with its body a JSON-encoded attributes list to the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2/Contacts
with the Content-Type header set to application/json, and the request body as (for example):
{"firstName":"John","lastName":"Smith","visibility":1,"email":"johnsmith@example.com"}
If creation of the contact is successful, the server should respond with status code 201 ("Created"), and the response should contain a Location header with the full URL (including protocol) of the newly created contact (in addition to all the attributes of the new contact). If for example the new contact's ID is 123, that URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root would be
index.php/api2/Contacts/123.json
and a GET request to that URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root would elicit a response from the server whose body contains a JSON-encoded list of attributes.
URI Formats, Terminology and Conventions
Note, the above example, the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root to which the POST request is sent (to create the contact) is referred to in this documentation as a base URI. Base URIs, when requested using the GET method, return a JSON-encoded array, each entry in the array corresponding to a record and being a dictionary of column:value pairs. So for example, if sending GET to the contacts model base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2/Contacts
the response would look like this:
[...,{"email": "johnsmith@example.com","firstName": "John","lastName": "Smith",...},...]
Whenever a URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root points to an object or resource uniquely identified with a specific database record, that URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root is referred to as a direct URI. Direct URIs end in ".json" and respond to GET requests with JSON-encoded dictionary objects of column values for the record as it is in the database. So, the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root in the above example (index.php/api2/Contacts/123.json) would respond with:
{"email": "johnsmith@example.com","firstName": "John","lastName": "Smith",...}
Direct URIs will almost always end in ".json", and base URIs will not. In general, the following convention applies almost universally within the API: If the URI ends in ".json", the resource will be a JSON-encoded dictionary object. Otherwise, it will be a JSON-encoded array. In the latter case, if each element of the array is a dictionary object, the dictionary objects should have uniform structure.
Access Credentials
To use the API, you will need to obtain X2Engine API credentials, which include a username and an API key. An X2Engine user with administrative privileges can get or set API keys in the Users module administrator. Any user can authenticate via the API by visiting the Update page for any given user.
Explore the API Using Your Web Browser
Once you have API credentials, you can examine the web API using your web browser by making GET requests to locations within index.php/api2 (simply by typing them into your browser's location bar). You can get a nicer view of the data returned by the server by installing a JSON viewing plugin in your web browser. A recommended plugin for this purpose is JSONView, which is available for Firefox and for Google Chrome (it's an unofficial port, but the developer of the API and author of this article uses it).
Example 1: hello, world
Try visiting the following URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root within X2Engine:
index.php/api2/appInfo.json
Initially you will be prompted to enter the username and password to complete authentication; enter the API key corresponding to the user in the password field. The above URL should respond with a JSON string containing some basic info about the X2Engine application.
Example 2: direct access
You can get the ID of any given account record by going to it inside X2Engine as you normally would and examining the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root. It should generally look something like this:
index.php/accounts/32
or:
index.php/accounts/id/32
In both of the above examples, the primary key value (id) of the record in question is 32. To view it in the API:
index.php/api2/Accounts/32.json
Note how in the API, the first letter of "Accounts" in the direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root is capitalized. This is because active record data in the API is accessed not via specifying the module containing the active record class, or to which the class corresponds, but by specifying the actual class name to use when accessing (or querying) data.
Example 3: querying
index.php/api2/Actions?_order=-id&_limit=3
This will show you the last 3 action records (i.e. emails, call logs, to-do's) created in the system (which the current acting API user has permission to view), in descending order of their primary key values (column "id"). If you have no action records in your system, you should receive an empty array.
Prerequisites for API Applications
When writing an application to interface with X2Engine via the API, it is required or strongly recommended that your language/coding environment of choice:
- Have a JSON parsing and encoding library available
- Have a library for making HTTP requests which can:
- Set request headers
- Parse response headers and read the response status code
- Natively support requests using HTTP Basic Auth for access
- Read responses even when the response code is not in the "success" category (2xx)
- Make POST, PATCH/PUT and DELETE requests
- Can access the network
Many high-level languages, such as Perl, PHP, Python and Ruby, meet these requirements. The specific usage of these languages is beyond the scope of this article; you will need to refer to the documentation of the library/libraries in use.
It is expected in the near future that a growing number of official API access classes (each in a different programming language) will be available for quick and easy development of API applications.
Authentication
As stated before, the API uses "HTTP Basic" authorization. Many HTTP client libraries will have native methods of setting headers for HTTP basic auth. It is recommended that you use such a method for authentication and read the relevant documentation, rather than setting headers manually, as that will save time and more likely lead to quicker success.
In all other cases, to authenticate and access the API using this method, each request must include the Authorization header. To compose the header, first combine the username and API key into a single string with a colon, as:
{username}:{userKey}
Next, obtain the string in Base-64 encoding. For example, username:password in base 64 is dXNlcjpwYXNzd29yZA==. Thus, the resulting header would look like this:
Authorization: Basic dXNlcjpwYXNzd29yZA==
See also the the Wikipedia article on this topic.
Note: because headers are sent without any built-in encryption, it is highly recommended that you use the API over HTTPS (HTTP encrypted using TLS[[wikipedia:Transport Layer Security]] a method of connecting to a remote network host that encrypts traffic on any given network protocol that uses it.), if available, or make API requests only within a network where packets are not easily intercepted.
Model-based Input and Output
Most of the modules in X2Engine (i.e. Contacts) will each have a corresponding active record model. This model is what is customized whenever adding a custom field. It is essentially a PHP class that is a child of X2Model (see: X2Model and Dynamic Fields for more information). Almost all API-based functions involving such data objects will contain the name of that class in the URL, i.e.
index.php/api2/Accounts index.php/api2/Contacts/135/Actions index.php/api2/Contacts/112.json
In general, the base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root for functions pertaining to models is
index.php/api2/{_class}
where {_class} is the class. The direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root is generally:
index.php/api2/{_class}/{_id}.json
where {_id} is the ID of the record to access.
Getting Model Classes
From the following URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root one can obtain a list of models:
index.php/api2/models
Each model in the list is a dictionary containing:
modelName | The class of the model |
---|---|
title | The human-readable name of the model |
attributes | An array of attribute names |
To include only fully-supported classes versus partially-supported model classes, include the "partialSupport" parameter and have it equal zero:
index.php/api2/models?partialSupport=0
Fully-Supported Model Classes
As of this writing, X2Engine by default has the following model classes that are fully supported in the API — meaning, all or nearly all of the most essential functionality that is possible in X2Engine via a web browser, in terms of manipulation of persistent data storage, is also possible via the API.
- Accounts
- BugReports
- Contacts
- Campaign
- Opportunity
- Product
- Services
Additionally, any custom modules will also have corresponding active record models fully supported by the API. This should usually be the same name as the module, but without spaces and the first letter always capitalized. If in doubt, to find the model class corresponding to a given module (i.e. a custom module), look in the "models" sub-directory of that module. The name of the file excluding the extension (.php) should be the name of the class. For instance, in the file protected/modules/contacts/models/Contacts.php there should be the following line:
class Contacts extends X2Model {
Partially-Supported Models
Manipulation of data using the following models (or certain aspects of the following models) is not fully supported in the API as of this writing — meaning, while most operations are possible, some important functionality is not yet possible:
Actions | Actions can be created, updated, viewed, queried and deleted as all other model types. However:
The limitations of filtering by action description are endemic to how the "field" is actually stored in a different database table than the contacts, and the type of the column is TEXT. |
---|---|
Docs | Can be accessed/manipulated as with other models. However, "edit permissions" do not work the same way as they do in the application. |
Groups | Groups can be queried, viewed and created, albeit only by an administrative user, and in a very limited capacity. Users cannot be added to or removed from groups; manipulating the associated "group-to-user" data is not yet possible. |
Media | Media records can be accessed and manipulated as with any other model, but the API does not yet support directly uploading files to go with them. |
Quote | Quote records can be accessed and manipulated, but associated "line items" data cannot be viewed or manipulated. |
X2List | This data type (contact lists in X2Engine) can be accessed and manipulated, but the actual contents of the list (whether dynamic or static) cannot. |
Creating, Viewing Updating and Deleting Records
To create a record, perform a POST request to the base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root for the model, i.e.
index.php/api2/Contacts
to create a contact. As mentioned in the example in the #Introduction, the body of the request must be a JSON-encoded library of attributes to set in the model, and the Content-Type header must be set to application/json.
To view, update or delete a record, first determine its direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root within the API, as set in the Location header if creation was successful, or as determined via its class and id, i.e.
index.php/api2/Contacts/33.json
to specify a contact record with its id equal to 33.
To update a record, send a PUT or PATCH request to a direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root, and set the body and Content-Type header as one would in a POST request to create such a record. Finally, to delete the record, send a DELETE request to that same direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root. It is not necessary in the case of deletion to include a body or set the Content-Type header.
Working With Associated Actions
The Actions model is unique in that it can be "associated" with almost any other type of model record. Actions records comprise all "history" items on any given record, i.e. emails, calls logged, notes, calendar events and also plain actions. Actions that have an association with another model can be used via clean URIs that point to "within" the associated model.
URI Formats
To view/query all actions associated with an active record model of class {_class} and id {_id}, use the following base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root:
index.php/api2/{_class}/{_id}/Actions
For instance, one could find all actions, including emails, on contact id=1233, via:
index.php/api2/Contacts/1233/Actions
To view an individual action of id {_actionId}, one can use this direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root:
index.php/api2/{_class}/{_id}/Actions/{_actionId}.json
Creating, Updating and Deleting Actions
Similar to the the basic model access API function, PATCH, POST, PUT and DELETE requests can be sent to associated action URIs to create/modify/delete records just as those URIs can also be used to view data. POST to the base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root,
index.php/api2/{_class}/{_id}/Actions
to create a new action associated with model record of class {_class} and id {_id}. Then, using the direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root,
index.php/api2/{_class}/{_id}/Actions/{_actionId}.json
PATCH/PUT/DELETE requests can be used to modify/delete an existing associated action record.
Metadata Functions
There is "structural" metadata that one can retrieve through the API to more effectively determine how to proceed with future API transactions. There are also some functions in the API that pertain to functionality associated with model records, but do not modify data within the records themselves, and create associated metadata.
Fields
One can access field metadata for a given model class by using the following base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root (which supports querying):
index.php/api2/{_class}/fields
One can directly access the metadata of a field by its name via the following direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root format:
index.php/api2/{_class}/fields/{_fieldName}.json
For instance, this URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2/Contacts/fields/leadSource.json
would respond with:
{"id":"88", "modelName":"Contacts", "fieldName":"leadSource", "attributeLabel":"Lead Source", "modified":"0", "custom":"0", "type":"dropdown", "required":"0", "uniqueConstraint":"0", "safe":"1", "readOnly":"0", "linkType":"103", "searchable":"0", "relevance":"", "isVirtual":"0","defaultValue":null,"keyType":null}
Field-Level Permissions
Any given user's access level to a field can be controlled by assigning them to a role and then setting field permissions for that role via Manage Roles under Admin.
A GET to the following will respond with a dictionary of active record model attributes, each value corresponding to field-level access permissions for that field granted the current acting API user.
index.php/api2/{_class}/fieldPermissions.json
For example, as the default administrator, for model Contacts, getting the following:
index.php/api2/Accounts/fieldPermissions.json
will respond with:
{"leadtype":2, "leadSource":2, "leadstatus":2, "leadDate":2, "leadscore":2, "interest":2, "dealvalue":2, "closedate":2, "rating":2, "dealstatus":2, "name":2, "nameId":1, "id":1, "website":2, "type":2, "visibility":2, "annualRevenue":2, "phone":2, "tickerSymbol":2, "address":2, "city":2, "state":2, "country":2, "zipcode":2, "parentAccount":2, "primaryContact":2, "employees":2, "assignedTo":2, "createDate":1, "description":2, "lastUpdated":1, "lastActivity":1, "updatedBy":1}
For each of these entries, the number associated with the field indicates the following:
0 | No access; when directly accessing a model record, the response data will not include the content of that field |
---|---|
1 | Read-only access; responses will include the content of that field, but any input to that field will be discarded |
2 | Read/write access. The current API user can both view and edit data in the field. |
Zapier-Friendly Fields
There is similarly a dynamic fields API action that returns an array of fields intended for use by Zapier. The object format returned from this action is described in Action Fields (Custom) in the Zapier developer documentation.
The base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root is:
index.php/api2/{_class}/zapierFields
This action is generally useful for API usage insofar as it will also return ranges of acceptable values for each field, if applicable, in the choices property. For example, if the type of a field is dropdown, the dropdown options will be returned in the choices property of each element in the returned array. Similarly, if the type of the field is assignment, the element's choices property will include a list of users and groups. Furthermore, it has the ability to easily select only fields of a given permission level or greater. For this, use the _permissionLevel parameter. For example, to get all writable fields in Contacts:
index.php/api2/Contacts/zapierFields?_permissionLevel=2
(see #Field-Level Permissions for more information)
Unfortunately, the action does not support querying, although it does not need to for its intended purpose.
Dropdowns
Note, to get a list of acceptable values for a given model in cases when the field type is not dropdown, use the choices property of data returned by #Zapier-Friendly Fields.
Some fields, i.e. lead source in contacts, are of type "dropdown"; their content is intended to be either blank, or an option in a static list. Dropdown menus can be queried at base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2/dropdowns
Dropdown fields can also be directly accessed via
index.php/api2/dropdowns/{_id}.json
To find out if a field is of type dropdown, and which dropdown menu it uses: the value for type in the field's metadata record should be "dropdown", and the linkType field should contain the dropdown's ID. So, using the example in #Fields, the corresponding dropdown record is at
index.php/api2/dropdowns/103.json
which contains:
{"id":"103", "name":"Lead Source", "options":{"None":"None", "Google":"Google", "Facebook":"Facebook", "Walk In":"Walk In"}, "multi":"0", "parent":null, "parentVal":null}
Note, for convenience's sake the "options" field won't be returned verbatim as the raw JSON (that's how the options are stored). Rather, that field will be decoded into a sub-dictionary of the overall object.
Relationships
It is possible to create, view, and delete relationships between supported API models in X2Engine via the API.
URI Formats
Relations functionality is in general accessed within the following base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root:
index.php/api2/{_class}/{_id}/relationships
So, to view all relationships going to or from account 131:
index.php/api2/Accounts/131/relationships
To view the contents (related model class and ID) of a specific relationship on the account (let's say the relation record has its id=304281 for instance):
index.php/api2/Accounts/131/relationships/304281.json
The Relationships active record model has the following attributes that can be used in queries:
- id
- Unique numeric identifier for the relationship
- firstType, firstId
- The model class and record ID at one end of the relationship, respectively
- secondType, secondId
- The model class and record ID at the other end of the relationship, respectively
For instance, to find all outgoing relationships with Accounts to contact id=126:
index.php/api2/Contacts/126/relationships?secondType=Accounts
Adding/Removing Relationships
To create a new relationship, sent POST to the base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root.
To remove a relationship, send DELETE to the direct URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root of the record, i.e. index.php/api2/Accounts/131/relationships/304281.json in the earlier example.
Tags
All basic, fully-supported models in X2Engine should support tagging. Tags cannot be individually modified, but can only be created, viewed, queried and removed, in order to enforce preservation of the important metadata such as who added the tag and at what date.
URI Formats
Tags on a given model record can be retrieved via GET at the following base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root:
index.php/api2/{_class}/{_id}/tags
The response should be a flat array of tag names. For example, if account 51 has tags "#customer" and "#local", sending GET to the following URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root
index.php/api2/Accounts/51/tags
will yield:
["#customer","#local"]
To view more extensive metadata of the tag, i.e. who added the tag and at what date:
index.php/api2/{_class}/{_id}/tags/{_tagName}.json
i.e.
index.php/api2/Accounts/51/tags/local.json
The above will return a dictionary of x2_tags column names and values. Note, the tag name in the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root must either exclude the preceding hash mark or include it via its corresponding URL encoding sequence, %23. This is because the hash mark is a special character in the HTTP protocol and will interfere with proper resolution of the URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root. Using the above example:
index.php/api2/Accounts/51/tags/%23local.json
That URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root will return the exact same data as the previous URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root; they are considered equivalent.
Adding Tags to a Record
Adding tags also utilizes that same URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root scheme as with viewing tags. To add one or more tags, send them as string elements in a flat JSON-encoded array via POST to that location. For example, to use the previous example, one can apply the tags "#customer" and "#local" from "record 51" to record 52 by POST-ing the same JSON returned from a GET at:
index.php/api2/Accounts/51/tags
to:
index.php/api2/Accounts/52/tags
Removing Tags
To delete a tag, send a DELETE request to the direct viewing location of the tag. So, for instance, to delete "#local" from account 51, send DELETE to index.php/api2/Accounts/51/tags/local.json
Querying Data
Almost any "base" URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root, which can be used for accessing all records of a type or for creating new records of a type, can also be used for querying records of that type. Responses to queries (and GET requests to these URIs in general) will always be JSON-encoded arrays of records, each record represented as an attribute dictionary.
Options for searching, as well as attributes to match column values against (for filtering), are all specified as query parameters (a.k.a. "get parameters"). The search options, to protect against name collisions with column names, each have names that begin with an underscore, i.e. _order.
General Search Option Parameters
In queries, one can use a variety of advanced options that include sorting, pagination, partial matching, and in some cases tags.
Parameter | Meaning | Default | Usage |
---|---|---|---|
_escape | Wildcard usage | 1 | Set 0 in parameters to allow characters like "%" and "_" to be used as SQL wildcards in search filter attributes. Controls the resultant value of the $escape argument sent to CDbCriteria.compare() in configuring the search. Note, to perform wildcard searches properly, the parameter _partial must be set to 1 so that CDbCriteria uses LIKE for the value comparison. For info on SQL wildcards and comparisons, see: MySQL: String Comparison Functions |
_limit | Page size | may vary | Set to a number to control the maximum number of records to include in the results of the search. The default and maximum page size is 1000, and in Platinum Edition this default amount is user-configurable. |
_or | Use "OR" operator | 0 | Set to 1 to make the operator used for combining search criteria OR instead of the default, AND. |
_order | Sorting | none | Set equal to the name of a column to sort by, optionally prefixed with a plus or minus sign to specify ascending or descending order (respectively). For example, _order=-leadScore in a Contacts query sorts contacts by lead score with the highest-scored contacts first. Note, sorting applies not only to the current page but to the data set spanning all pages. Thus, if the total number of possible results is larger than the page size, the set of results shown in the current page will be affected. |
_page | Page number | 0 | The zero-starting-point page number of the data. Useful for when the query would return more results than the page size specified. |
_partial | Partial match | 0 | Set to 1 to enable partial matching in search filters. This parameter controls the value sent to CDbCriteria.compare() as the $partialMatch argument. If true, the LIKE comparison will be used; otherwise, full equality will be used as the comparison. |
_tagOr | Inclusive tag search | 0 | When performing tag-based searches, set to 1 to indicate to include records with any of the specified tags rather than all of them. |
_tags | Has tag(s) | none | When querying tag-supporting X2Model sub-classes (meaning, those which can be tagged), this can be included and set to a comma-delineated list of tags. This will restrict results to records having all of said tags, or if _tagOr is enabled, any of the tags. Note, tag names should not contain their preceding "#" (or, at least should not contain it without URL-encoding it) because "#" is a special character in the HTTP protocol that will interfere with how your request to the server is interpreted. |
Adding Query Parameters
Appending option parameters proceeds as it would for any script that can receive URL-encoded variables via the request: follow the base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root with a question mark, and delineate [name]=[value] parameter declarations with ampersands (note: this might be different, depending on your web server's configuration, but the nearly-ubiquitous default is ampersand-delineation). For example:
index.php/api2/Contacts?_limit=10&firstName=Harry&lastName=P%25&_partial=1&_escape=0&_order=+lastName
This will return the first ten contacts out the list of contacts having first name "Harry" and last name beginning with "P", sorted alphabetically by last name.
Searching For Models By Tag
In addition to the _tags search option, there is a "pretty" dedicated base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root format for tag searching:
index.php/api2/tags/{_tags}/{_class}
So, for instance, to find all contacts with the tags "#customer" and "#important":
index.php/api2/tags/customer,important/Contacts
The above is equivalent to
index.php/api2/Contacts?_tags=customer,important
Note, additional search parameters can also be included. For instance, to return the first ten most recently updated contacts with the above tags:
index.php/api2/tags/customer,important/Contacts?_order=-lastUpdated&_limit=10
The reason for this is to express tags as categories, and thus in a loose sense "folders" in which one would find records.
Web Hooks
To develop real-time integration, that is to say, to have data sent from X2Engine to a third-party service immediately when a triggering event occurs, the best method is web hooks. Note, there is also the means of sending web requests to external URLs via the "Remote API Call" X2Flow action. For more information about this feature, see the X2Flow documentation for this action.
While said X2Flow action may suffice in many basic use cases, there are limitations to it that are addressed by web hooks:
- Configuring X2Flow cannot be performed via the API
- The action (making a web request) cannot be performed on a per-user basis (i.e. making a different request for each user)
- The X2Flow user interface is not available in the open source edition of X2Engine
In cases where the remote end, which will receive data from X2Engine, can be modified with custom code, web hooks are a method of "subscribing" to events in X2Engine via the API. Whenever an event would happen in X2Engine, X2Engine will submit payload data to a return URL specified in the original webhook request, as JSON-encoded data in the request body.
Creating Web Hooks
To create a hook with an event that depends on a model type (i.e. contact updated vs. account updated), send a JSON-encoded list of hook attributes via POST to the following URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root:
index.php/api2/{_class}/hooks
Or, to create a web hook associated with a generic event (that does not depend on model type), or a model of determined/unambiguous type (i.e. "Action Complete"):
index.php/api2/hooks
The POST-ed JSON-encoded dictionary should contain at least the following properties:
event | An event name; see #Supported Event Names and X2Flow | target_url | The remote URL to receive the payload | directPayload | (optional): a 1 or 0 (or true/false). See #Interpreting Payload Data for more information on this option
Supported Event Names and X2FlowEvents for which web hooks can be created are all named after X2Flow trigger class names. Trigger classes (whose files are named after them, like all other class files) are stored in the directory protected/components/x2flow/triggers In fact, any time that X2Flow::trigger is called, a corresponding call to ApiHook::runAll is also made, to execute all web hooks associated with that trigger event. The payload that is sent for all web hooks corresponding to that event is based on the value of the $params argument that is sent to X2Flow::trigger. In all cases, the payload is first converted to a pure array, i.e. not containing any objects or resource handles, so that it can be JSON-encoded and sent to the web hook target URL. The exact payload data will differ depending on the action; see "#Interpreting Payload Data" (coming soon) for further information. Interpreting Payload Data(section coming soon) Deleting Web Hooks(section coming soon) Interpreting Server ResponsesHTTP Response CodesIt is important to be able to read and interpret status codes (and for that matter, response headers) because in all success scenarios, the API does not respond with data envelopes. By this it is meant the act of wrapping a data model's attributes inside another array containing metadata about the status of the request. This is in effort to streamline and make more elegant code that handles response data. It is also for consistency's sake. A contacts model accessed as a resource object with name ending with .json is expected to be that contact, and not rather an array with server response info or other metadata. In general, the meanings of response codes closely or exactly follow the formal definitions as defined in RFC2616, as well as the informal definitions of unconventional status codes (See wikipedia:List of HTTP status codes). The following table lists each of the possible status codes that the API will respond with, the contexts in which they would appear, and what they indicate.
Error ObjectsIn all error responses produced by the API and not by the server itself, the body of the response will be a JSON containing metadata about the error and the response. This is for compatibility with less-than-satisfactory client libraries which cannot read the actual response code or headers, but might be able to read the response body when the code is not in the success (2XX) range. In such cases, the response will be a JSON-encoded object with at least the following properties:
In some cases, the response JSON may include the following additional properties:
|
---|