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.
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 Agones 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.
Warning
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 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.
Note
Using a GameServerAllocation is preferred in all other scenarios, as it gives Agones control over how packedGameServers
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:${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}]}}}
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
Player Tracking
Warning
The Player Tracking feature is currently Alpha, not enabled by default, and may change in the future.
Use the Feature Gate PlayerTracking
to enable and test this feature.
See the Feature Gate documentation for details on how to enable features.
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 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.
$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/count
Response:
{"count":"2"}
Example
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"]}
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.