BattlePlace.ioα Documentation About

API Reference version 1a

Alpha version

This API version is in development and is not stable. Do not use it in release versions of your software.

Client API

Client authentication

Authenticate client with one of the allowed authentication backends:

HTTP request

POST /v1a/client/auth

Request parameters

Parameter Type Description
projectId string Project identifier
auth object Credentials
auth.itchJwtToken string itch.io JWT token
auth.steamEncryptedTicket string Steam encrypted ticket
auth.testKey string Project’s test key
auth.testId string integer Index of test user

The auth parameter must contain credentials for exactly one authentication backend.

Response fields

Field Type Description
status string "authenticated" or "notAuthenticated"
clientToken string Opaque client token.

Example request

{
	"projectId": "abcdefghijk",
	"auth":
		{
			"itchJwtToken": "abcdefghijk0123456789",
		}
}

Example of successful response

{
	"status": "authenticated",
	"clientToken": "abcdefghijk0123456789"
}

Example of unsuccessful response

{
	"status": "notAuthenticated",
	"error": "bad token"
}

Request match

Place authenticated client into match queue. Returns match token, which allows to request status of matching process.

HTTP request

POST /v1a/client/match

Request headers

Header Description
Authorization Format: "Bearer " + clientToken

Request parameters

Parameter Type Description
clientToken string clientToken from authentication step
teamSizes array of integers Number of players in each team in a future game session
maxMatchTime integer How long to wait for match
matchTag string (optional) Additional parameter for match queue
serverTag string (optional) Additional parameter for match queue
info any (optional) Arbitrary information about player, automatically shared with all players in a session

Response fields

Field Type Description
matchToken string Match token allows to get status of matching process.

Example request

Authorization: Bearer CLIENT_TOKEN
{
	"teamSizes": [1, 1],
	"maxMatchTime": 30,
	"matchTag": "hardcore_mode",
	"info":
		{
			"ip": "1.2.3.4",
			"port": 1234
		}
}

Example response

{
	"matchToken": "MATCH_TOKEN"
}

Get match status

Retrieve status of matching process.

HTTP request

GET /v1a/client/match/{matchToken}

(replace {matchToken} with actual match token)

Request headers

Header Description
Authorization Format: "Bearer " + clientToken

Request parameters

None.

Response fields

Field Type Description
status string notFound, inProgress, matched or failed
session.externalSessionId string Random session id
session.sessionToken string Session token allows to upload session results
session.teams array of array of objects Description of teams
session.teams[i][j].info any (optional) Arbitrary information about player, specified in info parameter when requesting match
session.teams[i][j].ourTicket string Ticket for presenting by us to this player in order to authenticate with them
session.teams[i][j].theirTicket string Ticket this player must present to us in order to authenticate themselves
session.teamIndex integer Index of a team we are in
session.mateIndex integer Our index within a team
session.server object or null Server information, if there’s a server
session.server.info any (optional) Arbitrary information specified by server
session.server.ourTicket string Ticket for presenting to server in order to authenticate
reason string Failure reason, in case status is failed

Example in-progress response

{
	"status": "inProgress"
}

Example matched response

This example corresponds to the match request example above.

Note that ourTicket and theirTicket are missing for our player, as we don’t need to authenticate with ourselves.

{
	"status": "matched",
	"session":
	{
		"externalSessionId": "EXTERNAL_SESSION_ID",
		"sessionToken": "SESSION_TOKEN",
		"teams":
			[
				[
					{
						"info":
							{
								"ip": "1.2.3.4",
								"port": 1234
							},
						"ourTicket": null,
						"theirTicket": null
					}
				],
				[
					{
						"info":
							{
								"ip": "5.6.7.8",
								"port": 5678
							},
						"ourTicket": "CLIENT_0_TICKET_FOR_CLIENT_1",
						"theirTicket": "CLIENT_1_TICKET_FOR_CLIENT_0"
					}
				]
			],
		"teamIndex": 0,
		"mateIndex": 0,
		"server":
			{
				"info":
					{
						"ip": "9.10.11.12",
						"port": 4321
					},
				"ourTicket": "CLIENT_0_TICKET_FOR_SERVER",
				"theirTicket": "SERVER_TICKET_FOR_CLIENT_0"
			}
	}
}

server field is null for sessions without server.

Player-to-player tickets (ourTicket and theirTicket fields) are always presented, even for sessions with server, just in case players still need to establish P2P connections.

Cancel match

Cancel matching process.

HTTP request

DELETE /v1a/client/match/{matchToken}

(replace {matchToken} with actual match token)

Request headers

Header Description
Authorization Format: "Bearer " + clientToken

Request parameters

None.

Response fields

None.

Session results from client

Upload session results from client.

HTTP request

POST /v1a/client/session/{sessionToken}/result

(replace {sessionToken} with actual session token)

Request headers

Header Description
Authorization Format: "Bearer " + clientToken

Request parameters

Parameter Type Description
status string finished or cancelled
ranks array of integers Ranks of teams

Response fields

None.

Request matches for server

Request matches from server side.

HTTP request

POST /v1a/server/match

Request parameters

Parameter Type Description
projectId string Project identifier
projectServerToken string Server token from project settings
serverTag string (optional) Additional parameter for choosing sessions
name string Unique server name
info any (optional) Arbitrary information about server, which will be shared with clients automatically
timeout integer (optional) After what time to expire request for matches, in seconds

Response fields

Field Type Description
status string Must be registered

Example request

{
	"projectId": "abcdefghijk",
	"projectServerToken": "PROJECT_SERVER_TOKEN",
	"serverTag": "SERVER_TAG",
	"name": "EU_WEST_1",
	"info":
		{
			"ip": "9.10.11.12",
			"port": 4321
		},
	"timeout": 30
}

Example response

{
	"status": "registered"
}

Cancel request for matches for server

Cancel requesting matches from server side.

HTTP request

DELETE /v1a/server/match

Request parameters

Parameter Type Description
projectId string Project identifier
projectServerToken string Server token from project settings
name string Unique server name

Response fields

Field Type Description
status string Must be cancelled

Example request

{
	"projectId": "abcdefghijk",
	"projectServerToken": "PROJECT_SERVER_TOKEN",
	"name": "EU_WEST_1"
}

Example response

{
	"status": "cancelled"
}

Get sessions from match request for server

Get sessions on server side.

HTTP request

POST /v1a/server/match/sessions

Request parameters

Parameter Type Description
projectId string Project identifier
projectServerToken string Server token from project settings
name string Unique server name

Response fields

Field Type Description
sessions array of objects Sessions objects
sessions[i].externalSessionId string Random session id
sessions[i].serverSessionToken string Server session token
sessions[i].teams array of array of objects Description of teams in a session, in the same format as in client match response
sessions[i].matchTag string Match tag
sessions[i].serverTag string Server tag

Example request

{
	"projectId": "abcdefghijk",
	"projectServerToken": "PROJECT_SERVER_TOKEN",
	"name": "EU_WEST_1"
}

Example response

{
	"sessions":
		[
			{
				"externalSessionId": "EXTERNAL_SESSION_ID",
				"serverSessionToken": "SERVER_SESSION_TOKEN",
				"teams":
					[
						[
							{
								"info":
									{
										"ip": "1.2.3.4",
										"port": 1234
									},
								"ourTicket": "SERVER_TICKET_FOR_CLIENT_0",
								"theirTicket": "CLIENT_0_TICKET_FOR_SERVER"
							}
						],
						[
							{
								"info":
									{
										"ip": "5.6.7.8",
										"port": 5678
									},
								"ourTicket": "SERVER_TICKET_FOR_CLIENT_1",
								"theirTicket": "CLIENT_1_TICKET_FOR_SERVER"
							}
						]
					],
				"matchTag": "MATCH_TAG",
				"serverTag": "SERVER_TAG"
			}
		]
}

Session results from server

Upload session results from server.

HTTP request

POST /v1a/server/session/{serverSessionToken}/result

(replace {serverSessionToken} with actual server session token)

Request parameters

Parameter Type Description
status string finished or cancelled
ranks array of integers Ranks of teams

Response fields

None.