XP-Dev.com Documentation

Old Platform API User Guide & Documentation

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.

Introduction

XP-Dev.com provides a simple REST-like HTTP API for integration with your applications, tools and system. It understands JSON and XML formats.

API Tokens

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.

Generate Token

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

Marshalling Formats

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

SSL

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.

End Point

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

Responses

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>

Error messages

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>

Testing the API

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

Request Methods

The following request methods in general illustrate the actions being performed:

HTTP Request Method Action
GET Read
POST Create
DELETE Delete
PUT Update

Further Documentation

There are some exceptions to this rule, all detailed in the following sections:

Feel free to contact us if you need any assistance.