REST Game Server Client API

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

SDK Functionality

The REST API can be accessed from http://localhost:${AGONES_SDK_HTTP_PORT}/ from the game server process. AGONES_SDK_HTTP_PORT is an environment variable automatically set for the game server process by Code Blind to support binding the REST API to a dynamic port. It is advised to use the environment variable rather than a hard coded port; otherwise your game server will not be able to contact the SDK server if it is configured to use a non-default port.

Generally the REST interface gets used if gRPC isn’t well supported for a given language or platform.

Generating clients

While you can hand write REST integrations, we also have a set of generated OpenAPI/Swagger definitions available. This means you can use OpenAPI/Swagger tooling to generate clients as well, if you need them.

For example, to create a cpp client for the stable sdk endpoints (to be run in the agones home directory):

docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/sdks/swagger/sdk.swagger.json  -l cpprest -o /local/out/cpp

The same could be run for alpha.swagger.json and beta.swagger.json as required.

You can read more about OpenAPI/Swagger code generation in their Command Line Tool Documentation

Reference

Lifecycle Management

Ready

Call when the GameServer is ready to accept connections

• Path: /ready
• Method: POST
• Body: {}

Example

curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/ready

Health

Send a Empty every d Duration to declare that this GameServer is healthy

• Path: /health
• Method: POST
• Body: {}

Example

curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/health

Reserve

Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation.

• Path: /reserve
• Method: POST
• Body: {"seconds": "5"}

Example

curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve

Allocate

With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as Allocated. For those scenarios, this SDK functionality exists.

Example

curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate

Shutdown

Call when the GameServer session is over and it’s time to shut down

• Path: /shutdown
• Method: POST
• Body: {}

Example

curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown

Configuration Retrieval

GameServer

Call when you want to retrieve the backing GameServer configuration details

• Path: /gameserver
• Method: GET

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/gameserver

Response:

{
    "object_meta": {
        "name": "local",
        "namespace": "default",
        "uid": "1234",
        "resource_version": "v1",
        "generation": "1",
        "creation_timestamp": "1531795395",
        "annotations": {
            "annotation": "true"
        },
        "labels": {
            "islocal": "true"
        }
    },
    "status": {
        "state": "Ready",
        "address": "127.0.0.1",
        "ports": [
            {
                "name": "default",
                "port": 7777
            }
        ]
    }
}

Watch GameServer

Call this when you want to get updates of when the backing GameServer configuration is updated.

These updates will come as newline delimited JSON, send on each update. To that end, you will want to keep the http connection open, and read lines from the result stream and and process as they come in.

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/watch/gameserver

Response:

{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}

The Watch GameServer stream is also exposed as a WebSocket endpoint on the same URL and port as the HTTP watch/gameserver API. This endpoint is provided as a convienence for streaming data to clients such as Unreal that support WebSocket but not HTTP streaming, and HTTP streaming should be used instead if possible.

An example command that uses the WebSocket endpoint instead of streaming over HTTP is:

curl -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: ExampleKey1234567890===" -H "Sec-WebSocket-Version: 13" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/watch/gameserver

The data returned from this endpoint is delimited by the boundaries of a WebSocket payload as defined by RFC 6455, section 5.2. When reading from this endpoint, if your WebSocket client does not automatically handle frame reassembly (e.g. Unreal), make sure to read to the end of the WebSocket payload (as defined by the FIN bit) before attempting to parse the data returned. This is transparent in most clients.

Metadata Management

Set Label

Apply a Label with the prefix “agones.dev/sdk-” to the backing GameServer metadata.

See the SDK SetLabel documentation for restrictions.

Example

curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label

Set Annotation

Apply an Annotation with the prefix “agones.dev/sdk-” to the backing GameServer metadata

Example

curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation

Counters and Lists

Counters

In all the Counter examples, we retrieve the counter under the key rooms as if it was previously defined in GameServer.Spec.counters[room].

For your own Counter REST requests, replace the value rooms with your own key in the path.

Alpha: GetCounter

This function retrieves a specified counter by its key, rooms, and returns its information.

Example

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/counters/rooms

Response:

{"name":"rooms", "count":"1", "capacity":"10"}

Alpha: UpdateCounter

This function updates the properties of the counter with the key rooms, such as its count and capacity, and returns the updated counter details.

Example

curl -d '{"count": "5", "capacity": "11"}' -H "Content-Type: application/json" -X PATCH http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/counters/rooms

Response:

{"name":"rooms", "count":"5", "capacity":"11"}

Lists

In all the List examples, we retrieve the list under the key players as if it was previously defined in GameServer.Spec.lists[players].

For your own List REST based requests, replace the value players with your own key in the path.

Alpha: GetList

This function retrieves the list’s properties with the key players, returns the list’s information.

Example

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/lists/players

Response:

{"name":"players", "capacity":"100", "values":["player0", "player1", "player2"]}     

Alpha: UpdateList

This function updates the list’s properties with the key players, such as its capacity and values, returns the updated list details. This will overwrite all existing List.Values with the update list request values. Use addValue or removeValue for modifying the List.Values field.

Example

curl -d '{"capacity": "120", "values": ["player3", "player4"]}' -H "Content-Type: application/json" -X PATCH http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/lists/players

Response:

{"name":"players", "capacity":"120", "values":["player3", "player4"]}

Alpha: AddListValue

This function adds a new value to a list with the key players and returns the list with this addition.

Example

curl -d '{"value": "player9"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/lists/players:addValue

Response:

{"name":"players", "capacity":"120", "values":["player3", "player4", "player9"]}

Alpha: RemoveListValue

This function removes a value from the list with the key players and returns updated list.

Example

curl -d '{"value": "player3"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/v1alpha1/lists/players:removeValue

Response:

{"name":"players", "capacity":"120", "values":["player4", "player9"]}

Player Tracking

Alpha: PlayerConnect

This function increases the SDK’s stored player count by one, and appends this playerID to GameServer.Status.Players.IDs.

Example

curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connect

Response:

{"bool":true}

Alpha: PlayerDisconnect

This function decreases the SDK’s stored player count by one, and removes the playerID from GameServer.Status.Players.IDs.

Example

curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/disconnect

Response:

{"bool":true}

Alpha: SetPlayerCapacity

Update the GameServer.Status.Players.Capacity value with a new capacity.

Example

curl -d '{"count": 5}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity

Alpha: GetPlayerCapacity

This function retrieves the current player capacity. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

curl -d '{}' -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity

Response:

{"count":"5"}

Alpha: GetPlayerCount

This function retrieves the current player count. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/count

Response:

{"count":"2"}

Alpha: IsPlayerConnected

This function returns if the playerID is currently connected to the GameServer. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected/uzh7i

Response:

{"bool":true}

Alpha: GetConnectedPlayers

This function returns the list of the currently connected player ids. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected

Response:

{"list":["uzh7i","3zh7i"]}