API v3 usage

API v3 endpoint prefix

Throughout these documentation pages we will refer to API endpoints like this:

GET /deploymentEnvironment

This is not a complete endpoint. You must prefix this with the API uri and API version tag:

https://api.i3d.net/v3/

That results in the complete URL:

GET https://api.i3d.net/v3/deploymentEnvironment

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:

https://www.i3d.net/docs/api/v3/

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:

POST /applicationInstance/{applicationInstanceId}/start

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:

{
  "errorCode": 10001,
  "errorMessage": "Entity not found",
  "errors": [
    {
      "property": "propertyName",
      "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:

Response Code	Description
401 Unauthorized	When authentication with your API key failed.
403 Forbidden	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.

Table 1: HTTP response codes for errors

Caching

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.