API v3 Usage
API v3 endpoint prefix
Throughout these documentation pages we will refer to API endpoints like this:
This is not a complete endpoint. You must prefix this with the API uri and API version tag:
That results in the complete URL:
API v3 authentication
Authentication occurs via an API key. Creation and usage is explained in the API Authenticaton chapter.
API v3 endpoint documentation
All endpoints presented by the API including their input and output headers, parameters, request and response objects are documented at the following URL:
REST / CRUD
Our API v3 is based upon REST principles. It is however mostly used as a CRUD API. This means that you are almost always working with objects that you can Create, Read, Update and Delete. Even when you initiate a process like starting a game server with:
With this POST request you are still creating an object (a Task) that represents the process of starting an application instance and allows you to track that process. As such nearly all endpoints (unless stated otherwise) will return one or more objects, except certain DELETE requests, which will return
204 No Content with no response body.
Response output for valid requests
All valid GET, POST and PUT requests return a
200 OK response code and an array of objects in JSON format in the response body. Even if the response contains only one object you will still get an array with that one object inside.
DELETE requests always return a
204 No Content without a response body.
Response output for erroneous requests
In case your API request triggered an error, an error object will be returned:
"errorMessage": "Entity not found",
"message": "Error message"
The Error object contains an errorCode allowing you to programmatically handle it. There also is an errorMessage for humans to read.
Additionally an array of errors is returned in the object for additional information on what went wrong. E.g. if you have errors in a submitted object, this array will contain the error specifics.
Further reading: handling API errors
HTTP response codes for erroneous requests
Erroneous requests will have any of the following HTTP response codes, depending on the type of error:
|When authentication with your API key failed.
|When you are not allowed to perform a certain action
E.g. when your IP is banned by the system,
or when you are attempting to perform an action outside of the allotted time window.
|404 Not Found
|When a requested entity could not be found.
|422 Unprocessable Entity
|When a submitted entity contains errors. The specific errors will be mentioned in the returned Error object.
|500 Internal Server Error
|When there was an internal problem with the server or API.
A RESTful architecture can allow for caching of individual elements returned by the API. However we recommend you do not cache any elements, because they may be altered by other people or services at any point in time. As such we do not indicate caching hints in our API responses.