REST API Reference

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.

Authenticating

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

Interpreting Status Codes

It is important to be able to read and interpret status codes (and for that matter, response headers) because the API does not use data envelopes. By this it is meant the act of wrapping a data model's attributes inside another array containing metadata. 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	Meaning	Request types
200	Generic success method	All except DELETE
201	A record was created; see the value of the Location response header for its URL in the API	POST