# 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](/game-hosting/overview/apiv3-authentication.md).

## 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/`](/api/api_general.md)

## 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 **C**reate, **R**ead, **U**pdate and **D**elete. 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](/game-hosting/overview/apiv3-error-codes.md) 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](/game-hosting/overview/apiv3-error-handling.md)

## 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](/game-hosting/overview/apiv3-authentication.md) failed.                                                                                                   |
| 403 Forbidden             | <p>When you are not allowed to perform a certain action<br>E.g. when your IP is banned by the system,<br>or when you are attempting to perform an action outside of the allotted time window.</p> |
| 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/game-hosting/overview/apiv3-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.