Manage Request

In this section, we will show a basic example on how you can manage a session request from start to finish.

Let's say we have an application version set with Seat, four sockets, and autodeploy. You should backtrack in the session's documentation if you are unfamiliar with these terms.

Create the Initial Request

Our matchmaker has determined that players with IP addresses 1.2.3.4 and 5.6.7.8 want to play together. The matchmaker will send a request to create a session for them. You can find the full API documentation here.

We do not currently have a deployment to host our session request, so Arbitrium will automatically create one for our two players.

It is not ideal to query the API repeatedly to check if the session is ready. To avoid this, you can use a webhook, which is the recommended practice.

POST - /v1/session

{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4", "5.6.7.8"],
  "continent": "North America",
  "webhook_url": "https://my-webhook.com/callback"
}

Handling the Session Statuses

You will receive the same body whether you choose to use the webhook or to make GET requests. The session GET body contains various status and keys, but you only need to manage the status key. The three statuses you should handle are Ready, Error, and Unprocessable.

Error and Unprocessable

If your session is in either of these two statuses, it means that we were unable to link your session to a ready deployment. As a result, you will not have a URL to connect your players. It is important that you handle these statuses within your backend. It can happen for various reasons.

• You did not activate the autodeploy option so no deployments are available or there all at full capacity.

• We could not deploy your application version due to bad configuration.

Ready

When your session's status is Ready, it means that it is ready for your players to connect to the deployment. You can take the connection URL in deployment ports part of the GET body.

GET - /v1/session/{session_id}

{
  "session_id": "bc4d21eaf686-S",
  "status": "Ready",
  "deployment": {
    "request_id": "628572d11014",
    "fqdn": "628572d11014.st.edgegap.net",
    "ports": {
      "80": {
        "link": "628572d11014.st.edgegap.net:32072"
      }
    }
  }
}

There is more information in the body, but we have removed what is not related to the example for clarity.

Initializing, Seeking, Waiting

These are pending statuses, meaning that they occur when we are currently analyzing which deployment should host your session or when we are currently deploying a new deployment. You don't really need to handle these statuses.

Deleting a Session

When you determine that you need to delete the session, whether because you're disconnecting the connection between the server and your players and/or the match is over, you need to send us a deletion request.

You can simply delete a session with a DELETE request to /v1/session/{SESSION_ID}. Your session will go into a Terminating state before it's not available anymore.

As mentioned earlier, sessions are not physical connections, and therefore, you need to handle the physical connection and disconnection of your players. These manipulations should be in sync with the creation and deletion of sessions. If you do not delete your sessions, it will result in false session socket usage, and you will end up consuming a lot more resources than needed. It's important to note that Edgegap is not able to determine when your players should be connected to the server or not, so you need to handle this on your backend.

Basic Filtering

You can filter the sessions to enforce a specific location such as a country, continent, or city. You can also specify a latitude and longitude, and the deployment will be made as close as possible to that geographical point. You can see the full list of filters here. This can be helpful to use in your matchmaking system.

In the next section, we will show you how you can do some advanced filtering using Selectors and tags on your deployments.

Session Webhook Call-flow

When you create a session, you can provide a webhook URL to receive updates on the session's status. This is a more efficient way to manage your sessions than polling the API.

The following sequence diagram illustrates the call-flow of a session webhook.