This user guide only applies if your account and project is on our old platform, i.e. if your project's URL begins with https://xp-dev.com rather than https://<your-account>.xp-dev.com. If your account is on our new platform, you should be using this user guide instead.
XP-Dev.com provides a simple REST-like HTTP API for integration with your applications, tools and system. It understands JSON and XML formats.
To be able to use the API, each request has to be authenticated against an API token. To generate an API token, you can head to your XP-Dev.com settings page.
The following header needs to be added to all HTTP requests when interacting with the API:
X-XPDevToken: <your token>
For e.g.:
X-XPDevToken: abcabac123456789
XP-Dev.com's API end point understands XML and JSON formats. Switching
between formats can be done using the header fields Accept
and
Content-Type
. The Accept
header controls the format of responses
from the API, whereas the Content-Type
header controls the format of
requests to the API:
Message Format | Accept Header |
Content-Type Header |
---|---|---|
XML | text/xml | text/xml |
JSON | application/json | application/json |
If none of these headers are specified, XP-Dev.com's API end point
assumes all responses are in JSON format. HTTP methods PUT
and
POST
need to specify the header Content-Type
As much as possible, SSL should be used when interating with the API. All examples below use https:// rather than it's non-SSL equivalent.
At time of writing, the API is currently on version 1. All requests
should begin with the base URL https://xp-dev.com/api/v1/...
JSON API responses are normally encapsulated around response
tags:
{"response": <some valid JSON object>}
XML responses are not encapsulated:
<xml-object-type>
<attribute1>value1</attribute1>
...
</xml-object-type>
In general, the API will return valid HTTP errors and these should be looked at the first instance. However, certain operations will have more descriptive error messages.
JSON example:
{
"error": {
message": "Permission denied"
}
}
XML example:
<error>
<message>Permission denied</message>
</error>
Curl is the swiss army knife for testing HTTP
REST-like APIs. In the following examples, it is assumed that the header
X-XPDevToken
has been specified to curl when making requests. For
e.g.:
curl -v -H 'X-XPDevToken: abcabac123456789' https://xp-dev.com/api/v1/...
You should specify a marshalling format as much as possible. For e.g. to use JSON format for the API:
curl -v -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-XPDevToken: abcabac123456789' https://xp-dev.com/api/v1/...
The following request methods in general illustrate the actions being performed:
HTTP Request Method | Action |
---|---|
GET | Read |
POST | Create |
DELETE | Delete |
PUT | Update |
There are some exceptions to this rule, all detailed in the following sections:
Feel free to contact us if you need any assistance.