Skip to content

Latest commit

 

History

History
125 lines (92 loc) · 3.98 KB

sdk_rest_api.md

File metadata and controls

125 lines (92 loc) · 3.98 KB
Raw

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.

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

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

⚠️⚠️⚠️ /watch/gameserver is currently a development feature and has not been released ⚠️⚠️⚠️

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}]}}}