REST Game Server Client API

This is the REST version of the Agones Game Server Client SDK.

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

The REST API can be accessed from http://localhost:59358/ from the game server process.

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

Note: The SDK Server sidecar process may startup after your game server binary. So your REST SDK API calls should contain some retry logic to take this into account.

Generating clients

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

For example (to be run in the agones home directory):

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

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

Reference

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:59358/ready

Health

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

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

Example

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

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:59358/shutdown

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:59358/metadata/label

Set Annotation

Apply a 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:59358/metadata/annotation

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:59358/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:59358/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}]}}}

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.

Note: Using a GameServerAllocation is preferred in all other scenarios, as it gives Agones control over how packed GameServers are scheduled within a cluster, whereas with Allocate() you relinquish control to an external service which likely doesn’t have as much information as Agones.

Example

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