Skip to content

Home

Jump to bottom
Frank Versnel edited this page Aug 11, 2016 · 9 revisions

Introduction

Padrone is a HTTP web server that tracks running hosts and the clients that are playing on those hosts. It handles authentication of Itch.io, Steam, and Oculus accounts and allows players of these different platforms to play with one another.

To make use of Padrone for your own game you have to setup your own Padrone server and learn how to communicate with it from your game. This article will explain how to use the Padrone HTTP API.

Authentication

Each request in Padrone has to be authenticated, which means that to host or join a game a player has to have a valid Steam, Itch.io, or Oculus account and own the game on that specific platform. To add these credentials to a request Padrone requires you to add a X-Padrone-Auth header with the following data:

  • steam: A hex string of the Steam auth ticket obtained through the Steam API in your game.
  • itch.apikey: an API key obtained from the ITCHIO_API_KEY environment variable. See: https://itch.io/docs/itch/integrating/manifest.html for further details
  • itch.downloadkey: a user's download key
  • oculus: a user id then , and then a nonce obtained by the Oculus API

An example auth header looks like this: oculus:1013516932049277,h23OtmpjntSs1rIczq4ovFdWd57xWARXxLyXGtSSBk15vthjfacZRHFs6VIQIQVZ

All header strings should be base64 encoded.

Once authenticated Padrone caches the result of the authentication such that it does not have to make a third-party API call for each request. It's a good idea not to renew an auth ticket/nonce for each request because otherwise Padrone can't cache anything.

The API

Registering a host

Registers a host under the account provided in the auth header. If there is already a host registered with this account it will unregister that first before registering a new one.

Endpoint:

POST /app/register-host

Input (JSON):

{hostName: string,
 peerInfo: {internal: "127.0.0.1:8000", external: "127.0.0.1:8000"},
 password: null or string,
 isPrivate: boolean,
 version: string,
 maxPlayers: int}

Output:

StatusCode: OK or StatusCode: NotAcceptable

Unregistering a host

Unregisters a host

Endpoint:

POST /app/unregister-host

Input (JSON):

{externalEndpoint: "127.0.0.1:8000"}

Output:

StatusCode: OK

Pinging the host

Pings a host to indicate that it's still up and running. Also provides data on which clients are connected to this host such that Padrone can unregister the clients from this host if they're not there.

Endpoint:

POST /app/ping

Input (JSON):

{hostEndpoint: "127.0.0.1:8000",
 connectedClients: ["58de3852-30ce-4150-840a-ed30809418af", ...]}

Output:

StatusCode: OK or StatusCode: NotAcceptable

Joining a host

Allows clients to join a host and provides them with a sessionId and a secret to communicate with the host.

Endpoint:

POST /app/join

Input (JSON):

{hostEndpoint: "127.0.0.1:8000",
 password: optional string}

Output (JSON):

{sessionId: "58de3852-30ce-4150-840a-ed30809418af"
 secret: "28e28a4e-3358-4d60-859d-e39d1c614360"}

The sessionId identifies the client on the host and is only valid for this specific join session. The secret can be used a shared symmetrical key between the client and the host to communicate securely.

Leaving a host

Leave the host that the player is currently registered at.

Endpoint:

POST /app/leave

No input

*Output: *

StatudCode: OK

List hosts

Endpoint:

GET /app/list-hosts

Parameters:

  • version: a version string
  • hideFull: boolean. Default: true
  • hidePasswordProtected: boolean. Default: true
  • limit: int. Limits number of hosts returned. Default: 50

Output (JSON):

[{name: string,
  hostedBy: null or string,
  peerInfo: {internal: "127.0.0.1:8000", external: "127.0.0.1:8000"},
  isPasswordProtected: boolean,
  onlineSince: "2016-12-03T10:15:30.00Z",
  distanceInKm: null or int,
  country: null or string,
  version: string,
  playerCount: int,
  maxPlayers: int)},
 ...]

Get the player info

Allows the host to validate that a client has indeed called app/join on this host and retrieves player specific information like his or her Persona name and avatar.

Endpoint:

GET /app/player-info

Parameters:

  • sessionId: the client's session id.
  • hostEndpoint: the host's external endpoint

Output (JSON):

{sessionId: string,
 secret: string (the secret that can be used to encrypt traffic between host and client),
 playerInfo: {name: string,
              avatarUrl: url string,
              isAdmin: boolean,
              isDeveloper: boolean}}
Clone this wiki locally