© 2015 X2Engine Inc.
Difference between revisions of "REST API Reference"
| Line 4: | Line 4: | ||
This API within X2Engine, which can be accessed via the URI | This API within X2Engine, which can be accessed via the URI | ||
index.php/api2 | index.php/api2 | ||
| − | exclusively uses JSON for data input and output, | + | exclusively uses JSON for data input and output, operates via HTTP/S requests, tends to use similar URIs for both input and output (distinguishing operations via the request method) and uses a variety of server response codes to distinguish error scenarios in the case of an unsuccessful transaction. |
For example, to create a contact, one would send a <tt>POST</tt> request with its body a JSON-encoded attributes list to the URI | For example, to create a contact, one would send a <tt>POST</tt> request with its body a JSON-encoded attributes list to the URI | ||
| Line 13: | Line 13: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
If creation of the contact is successful, the server should respond with status code 201, and the response should contain a <tt>Location</tt> 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 would be <tt>index.php/api2/Contacts/123.json</tt>, and a GET request to that URI would elicit a response from the server whose body contains a JSON-encoded list of attributes. | If creation of the contact is successful, the server should respond with status code 201, and the response should contain a <tt>Location</tt> 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 would be <tt>index.php/api2/Contacts/123.json</tt>, and a GET request to that URI would elicit a response from the server whose body contains a JSON-encoded list of attributes. | ||
| + | |||
| + | When utilizing the API it is thus 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 | ||
| + | * Read responses even when the response code is not in the "success" category (2xx) | ||
| + | * Make <tt>POST</tt>, <tt>PATCH</tt>/<tt>PUT</tt> and <tt>DELETE</tt> requests | ||
| + | * Can access the network | ||
Revision as of 01:19, 2 May 2014
Introduction
This API within X2Engine, which 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
exclusively uses JSON for data input and output, operates via HTTP/S requests, tends to use similar URIs for both input and output (distinguishing operations via the request method) and uses a variety of server response codes to distinguish error scenarios in the case of an unsuccessful transaction.
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, 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.
When utilizing the API it is thus 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 * 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
