© 2015 X2Engine Inc.

REST API Reference

From X2Engine
Revision as of 23:11, 5 May 2014 by Demitri (talk | contribs) (Querying Data)
Jump to: navigation, search

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.

This article is currently a work in progress.

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.

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" 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 that method for authentication and read the relevant documentation rather than setting headers manually, as that will save time and more likely render successful results sooner.

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-centric API Functions

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

Basic Model Types

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, action completion and backdating (setting or overwriting the completion date) is not yet supported, because completeDate is a "read-only" field. Furthermore, associated "action timer" records (applicable only to Professional/Platinum edition) cannot be accessed or manipulated.
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.

Getting Model Attributes

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. Replace {_class} with the name of the model class.

 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.

To retrieve more comprehensive metadata for the fields of any given model, get the following:

 index.php/api2/{_class}/fields.json

That will return a JSON dictionary of all x2_fields records in the model, i.e. the field type, id, etc.

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, which should be:

 index.php/api2/{_class}

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 location within the API, as set in the Location header if creation was successful, or as determined via its class and id. It should be formatted as follows:

 index.php/api2/{_class}/{_id}.json

For example, a contact record with its id field equal to 33 can be accessed and manipulated at 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/Contacts/33.json

One can thus easily create model URIs using the above format if the id and class of the desired record are available.

To update a record, send a PUT or PATCH request for modifying objects, 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 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

Viewing actions associated with a record is as follows:

To view/query all actions on an active record model of class {_class} and id {_id}:

 index.php/api2/{_class}/{_id}/Actions

For instance, one could find all actions, including emails, on contact 1233, via:

 index.php/api2/Contacts/1233/Actions

To view an individual action of id {_actionId}:

 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 index.php/api2/{_class}/{_id}/Actions creates a new action associated with model record of class {_class} and id {_id}, and PATCH/PUT/DELETE requests to the "individual view" 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 can be used to modify/delete an existing associated action record.

Model Metadata API Functions

Some functions in the API pertain to functionality associated with model records, but that do not modify data within the records themselves, and create associated metadata. One example would be tagging a contact, which adds a record to the tags table and does not in itself change any part of the contact record. Performing such operations will use a mostly-similar URL scheme to the standard model operations, beginning with the model class. For instance, the following will query tags on contact id=624:

 index.php/api2/Contacts/624/tags

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 via

 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

Adding/Removing Relationships

To create a new relationship, sent POST to the "all relationships" 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.

To remove a relationship, send <tt>DELETE to the individual viewing 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 location:

 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 searching records of that type. 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, as of this writing, the _partial parameter must also be set to 1 in order to enable wildcard searches. For info on SQL wildcards, see: MySQL: String Comparison Functions
_limit Page size n/a (varies) Set to a number to control the maximum number of records to include in 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.
_page Page number 0 The zero-starting-point page number of the data. If the query would ordinarily return more results than the maximum 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.
_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.

Adding Query Parameters

Appending option parameters proceeds as it would for any script that can receive URL-encoded variables via the request: follow 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 with a question mark, and delineate [name]=[value] parameter declarations with ampersands (note: this might be different, depending on your server's configuration). For example:

 index.php/api2/Contacts?firstName=Harry&lastName=P%25&_limit=10&_escape=0&_order=+lastName&_partial=1

This will return the first ten contacts out the list of contacts having first name "Harry" and last name beginning with "P", using alphabetical ordering by last name.

Interpreting Server Responses

HTTP Response Codes

It 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.

Code Request type or usage scenario Meaning
Success (2XX)
200 GET, PATCH, PUT

Also, when adding tags via POST

OK. General success status
201 POST Created. A record was created; see the value of the Location response header for its URL in the API
204 DELETE No content. An action was completed but the server does not need to return any content. The body of the response will be empty.
Redirection (3XX)
303 GET

When requesting an object that exists but is not actually associated with the record specified in the request

See other. The requested resource is somewhere else. The Location header should contain the correct URL to the record.
Client Error (4XX)
400 All request methods/actions Invalid request. General status code for when something is missing, malformed or incorrect in the request headers/body.
401 All request methods/actions. Authentication failure or missing authentication credentials.
403 All request methods/actions. Forbidden. This may be because the user in API authentication does not actually have permission in X2Engine to perform the specified action (i.e. updating/viewing a particular record). In Platinum Edition, this code can also indicate that the IP address of the API client has been blocked.
404 All request methods/actions. Not found, or invalid 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 used whenever a specified record to retrieve directly does not exist, but also as a catch-all for a location that the API was not configured to interpret.
405 All request methods/actions Method not allowed. 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 is not malformed, but the method of the request being sent to the server is not permitted. An example would be sending a POST request, which is intended for creating new records, 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 of an existing record, or sending a DELETE/POST/PUT request to a "read-only" resource.
408 All methods; server-generated Request timeout. This code is not as of this writing not produced by the API; it might be returned by the web server itself.
413 All methods; server-generated Request entity too large. This code is not as of this writing not produced by the API; it might be returned by the web server itself.
415 PATCH, POST, PUT Unsupported media type. As of this writing, this happens only whenever the request is sent with a body and the Content-Type header is not set to "application/json"
422 PATCH, POST and PUT

When creating or updating a record

Unprocessable entity. This always indicates a data validation error when attempting to set fields of and save an active record model. The client is expected to resolve these issues and resubmit the data with all of the fields formatted in such a way that it is acceptable.
429 Platinum Edition only

All request methods/actions

Too many requests. When rate limiting is enabled in the API settings, the server will use this code to indicate that the API client has been making requests to the API too frequently. When this status is sent, the response should also contain a Retry-After header specifying the number of seconds to wait before trying again.
Server Error (5XX)
500 All request methods/actions Internal server error. General status for when something isn't right on the server. PHP and database errors will produce this status code.
501 All request methods/actions Not implemented. The API should use this code to denote that a given method, action, etc. is not yet available, but may be in the future.
503 Professional and Platinum Editions

All request methods/actions

Unavailable. X2Engine and/or its API service has been disabled/locked by an administrator.

Error Stubs

In 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:

httpHeaders A dictionary of HTTP headers that were set deliberately by the API (as opposed to automatically, by the web server software) in the response.
message A general message about what happened and why. This will in most cases also be saved in the API log.
error Boolean true/false, indicating if an error occurred.
status The HTTP status code that was sent in the response header

In some cases, the response JSON may include the following additional properties:

errors A dictionary of validation errors encountered when attempting to save an active record model; included with responses of status code 422.

The structure will be indexed by attribute name, each entry containing a list of applicable validation errors. It is essentially the resulting value of the CModel.errors property.