Public API

Overcast provides a set of public API that can be used to interact with the environment such as reading state or performing certain actions. In the following document we are going to learn the basics of how to invoke the public API and show some examples of usage.

Calling the API

The public API is invoked using the same url for every call, with the following format:

https://overcast.smartfoxserver.com/public_api/{command}/{p1}/.../{pN}

Where:

{command} is any valid API command available
{p1}/.../{pN} a variable number of parameters, required by the invoked command

Since the public API use standard HTTP protocol any HTTP client (browser, command line tool, language specific library) can be used to interact with it.

From the other end, the Overcast API will reply with a plain JSON object.

When a region identifier is needed, the following values can be used

EU (Frankfurt): eu-central-1
US (North Virginia): us-east-1
AP (Singapore): ap-southeast-1
AP (Mumbai): ap-south-1

Listing available SFS2X instances

The list_sfs command allows to obtain the list of available SmartFoxServer instances running in a specific app. The request format is as follows:

/public_api/list_sfs/{appId}/{regionId}

{appId} (required): is the unique id of your application
{regionId} (optional): the id of a region, to filter the servers only from that region

The API will reply with a list of server objects. For example:

[
  {
    "name": "Server1-EU",
    "ip": "18.159.129.242",
    "domain": "tictactoe-eu.mygamedomain.com",
    "region": "eu-central-1",
    "ccu": "1150"
  },
  {
    "name": "Server2-EU",
    "ip": "18.196.73.119",
    "domain": "words-eu.mygamedomain.com",
    "region": "eu-central-1",
    "ccu": "699"
  },
  {
    "name": "Server3-US",
    "ip": "34.205.72.152",
    "domain": "tictactoe-us.mygamedomain.com",
    "region": "us-east-1",
    "ccu": "2884"
  }
]

Each object has five properties:

Name of the server
IP address of the server
The domain name assigned to the server
Region of the server
Current CCU count

With this command clients can filter the available list of SFS instances by their source region and choose where to connect.

Listing available SmartFoxServer 2X Clusters

The list_clusters command allows to obtain the list of available SmartFoxServer Cluster Lobby Nodes running in a specific app. The request format is as follows:

/public_api/list_clusters/{appId}

{appId} (required): is the unique id of your application

The API will reply with a list of server objects. For example:

[
  {
	"name": "Lobby1-EU",
	"ip": "18.159.129.242",
	"domain": "tictactoe-eu.mygamedomain.com",
	"region": "eu-central-1",
	"ccu": "13227"
  },
  {
	"name": "Lobby2-US",
	"ip": "32.196.173.222",
	"domain": "tictactoe-us.mygamedomain.com",
	"region": "us-east-1",
	"ccu": "8946"
  }
]

Each object has five properties:

Name of the server
IP address of the server
The domain name assigned to the server
Region of the server
Current CCU count

With this command clients can filter the available list of Lobby Nodes by their source region and choose where to connect.