Examples

Instructions and examples of how to query game servers from the Octops Discover API.

How to consume data from the Octops Discover API?

  • You can use any kind of HTTP client that supports authentication like the commandline curl or a GUI.
  • Requests will be authenticated using the OCTOPS_API_TOKEN.
  • Examples of clients are https://www.postman.com/ and https://insomnia.rest/.
  • Once deleted, game servers will no longer be part of the response payload.
  • Game servers that were not updated or received a heartbeat in the last minute will not be part of the response payload.
curl -s --location --request GET 'https://api.beta.octops.dev/api/v1/gameservers?limit=1000' \
--header 'Authorization: Bearer [YOUR_OCTOPS_API_TOKEN]' | jq .

An example of a response is:

[
  {
    "name": "octops-virtual-2-z8ggf-tchkk",
    "namespace": "default",
    "labels": {
      "agones.dev/fleet": "octops-virtual-2",
      "agones.dev/gameserverset": "octops-virtual-2-z8ggf",
      "cluster": "gke-1.24",
      "region": "us-central-1"
    },
    "address": "192.168.10.9:7204",
    "gameserver_state": "Scheduled"
  },
  {
    "name": "octops-virtual-3-r9f8f-xbzlr",
    "namespace": "default",
    "labels": {
      "agones.dev/fleet": "octops-virtual-3",
      "agones.dev/gameserverset": "octops-virtual-3-r9f8f",
      "cluster": "gke-1.24",
      "region": "us-west-1"
    },
    "address": "192.168.10.47:7745",
    "gameserver_state": "Ready"
  },
  {
    "name": "octops-virtual-3-r9f8f-t4tb2",
    "namespace": "default",
    "labels": {
      "agones.dev/fleet": "octops-virtual-3",
      "agones.dev/gameserverset": "octops-virtual-3-r9f8f",
      "cluster": "gke-1.24",
      "region": "us-west-1"
    },
    "address": "192.168.10.24:7537",
    "gameserver_state": "Allocated"
  }
]

How to use filters?

Filters are applied by informing the field/value as part of the request query string. Below you can find the full list of fields and how they can be combined to create the desired query criteria. The order they appear in the URL does not matter.

Available fields

  • name: name of the game server.
  • namespace: namespace where the game server is running.
  • labels: key/value that represents labels present in the GameServer resource. It can be labels set statically by the Fleet manifest of dynamically by using the Agones SDK. Multiples labels must be separated by a comma. Only game servers that contains all labels will be returned.
  • address: the IP address and Port of the game server.
  • players_count: total number of players.
  • players_capacity: players capacity set on the game server.
  • players_ids: players ids separated by a comma. Ony game servers that holds all the ids will be returned.
  • state: game server state. I.e: Ready, Allocated, Scheduled.
  • limit: restricts the number of game servers to be returned (defaults to 100k). The default order is the created_timestamp field from the GameServer resource. You can find this value using kubectl describe gs [GS_NAME].

Numeric fields and logical operators

For fields of type int (players_count and players_capacity) a logical operator must be informed:

  • eq (equal)
  • gt (greater than)
  • lt (less than)
  • gte (greater than or equal to)
  • lte (less than or equal to)
  • in (equal to), not_in (not equal to)

Querying

Clients can request the Discover API endpoint https://discover.octops.io/api/v1/gameservers passing the query string parameters that will compose the filter.

Examples of query strings using filters:

# Find the game server using the name
GET name=octops-2dnqv-jmqgp

# Find game servers using labels
GET labels=cluster=gke-1.24,region=us-central1-1,game_version=1.0

# Find game servers using the address
GET address=10.23.3.12:7006

# Find game servers using players_ids
GET players_ids=10,23,45,99,134

# Find game servers using players_capacity >= 10
GET players_capacity=gte:10

# Find game servers using players_capacity <= 10
GET players_capacity=lte:10

# Find game servers using players_capacity = 10
GET players_count=eq:10

# Find game servers using players_capacity > 10
GET players_count=gt:10

# Find game servers using players_capacity < 10
GET players_count=lt:10

# Find game servers with gameserver_state='Allocated'
GET state=Allocated

# Find game servers with gameserver_state='Ready'
GET state=Ready

# # Find game servers using labels and players_count < 10
GET labels=region=us-central1-1&players_count=lt:10

# Find game servers with labels and players_capacity = 20
GET labels=region=us-central1-1,mode=deathmatch&players_capacity=eq:20

# Find game servers with labels and players_capacity >=10 and players_count = 33
GET labels=region=us-east-1,cluster=gke-1.22&players_capacity=gte:10&players_count=eq:33"

What is next?

  • Check the Discover API section to learn about the Octops Discover API reference.