Skip to main content

Getting Started

The Developer API allows you to configure the Matchmaker to suit your game, such as setting Queue options or defining how servers are assigned. It is accessible via an HTTP REST service, a gRPC service, and a web-based frontend.

Users wishing to access the Developer API require:

  • An HTTP or gRPC client.
  • An access token.

Overview​

There are three primary resource types, that exist in a hierarchy:

  • Project: A project or game, such as "Scavengers" or "speedy-racer-1999", and defines the authorization challenge that clients must meet to connect to the client API and list and join queues.
    • Queue: A queue within a project, such as a 4v4 queue, a CTF game mode queue, or a US queue, depending on the needs of the project. Defines the rules for matching players, and also how matches are assigned to game servers.
    • Platform: A provider of game servers that may be shared by multiple queues. This can be defined both at project or at queue level.

In the simplest configuration, a Project will have a single Queue backed by a single Platform. The queue defines matching rules and players can join it and get assigned a game server. The Platform defines a server provider such as zeuz which is used to start up game servers for the players.

All these resources can be accessed and modified via this service.

Resource naming​

All resources have a full, canonical address, such as projects/scavengers or projects/speedy-racer-1999/queues/solo - these are used throughout the developer API, and can be transformed directly into HTTP paths.

Additionally, resources can also be referenced by their equivalent ID (scavengers and speedy-racer-1999.solo, respectively) - although typically these are only used by the client API.

Quick Start​

HTTP​

Any modern HTTP tool or library that can also read/write JSON is sufficient for accessing the Developer API over HTTP. We recommend:

The base URL for the API is https://prd.matchmaker.os.i8e.io/v2/admin/, and requests take the form https://prd.matchmaker.os.i8e.io/v2/admin/projects/<prj>/queues/<queue>:forceStart.

The access token should be provided as an authorization header bearer value within the HTTP request, e.g.

Authorization: Bearer yoursecretaccesstoken

For instance, using HTTPie to list known projects:

http put "https://prd.matchmaker.os.i8e.io/v2/admin/projects" "Authorization: Bearer mysecret"

Then to create a queue:

http put "https://prd.matchmaker.os.i8e.io/v2/admin/projects/speedy-racer-1999/queues/solo" "Authorization: Bearer mysecret" \
  id="speedy-racer-1999.solo" \
  title="Solo Queue" \
  active:='false' \
  simple:='{"startSettings": {"playersToAllocate": 1}, "playerSettings": {"maxPlayers": 0}}' \
  static:='{"server": "127.0.0.1"}'

Or to create a platform:

http put "https://prd.matchmaker.os.i8e.io/v2/admin/projects/speedy-racer-1999/platforms/storc" "Authorization: Bearer mysecret" \
  id="speedy-racer-1999.storc" \
  title="IMS zeuz provider" \
  storc:='{ "projectId": "speedy-racer-1999", "allocationId": "a5c95500-bbe8-44d0-8381-35dc42cd3c46", "clientPort": "unreal" }'

Then to update a queue to activate it and increase the simple.playerSettings.maxPlayers value to 1:

http patch "https://prd.matchmaker.os.i8e.io/v2/admin/projects/speedy-racer-1999/queues/solo" "Authorization: Bearer mysecret" \
  active:=true \
  simple:='{"playerSettings": {"maxPlayers": 1}}'

(By default, HTTP patch requests will only modify the keys provided by the request.)