Metaplay SDK 32 Required

The Public Web Endpoints feature was introduced in SDK version 32.

Dependencies

• Game Server Architecture - This guide assumes you have working knowledge on the overall game server architecture. For a refresher, check out Game Server Architecture.
• Understanding Entities and Actors - The public web endpoints are a gateway to the backend's entities ecosystem, and the web server instance runs in the context of a dedicated actor. Take a look at Introduction to Entities and Actors if you're not familiar with them yet.

Overview

In addition to serving game clients via the custom binary protocol the game server is also capable of serving public HTTP requests. This is primarily useful for implementing integrations with 3rd party services that expect to be able to interact with the gameserver using HTTP, such as server-to-server REST callbacks for ad rewards.

The public web endpoint hostname is by default built from the gameserver hostname with prefix -public added as the least significant fragment of the subdomain. For example if the server hostname is tiny-squids.p1.metaplay.io then the public web endpoint would be tiny-squids-public.p1.metaplay.io. When running the server locally the public web endpoints are served at http://localhost:5560.

The game server runs an ASP.NET web server in the PublicWebApi actor that is by default placed on logic shards in non-singleton deployments. The infrastructure takes care of terminating HTTPS and routing the requests to available logic shards. Note that this implies that subsequent requests will not necessarily be handled by the same server instance, so if there is any state that must be maintained across requests then the state persistence has to be implemented via entity messaging or the database.

Adding a custom public web endpoint

Introducing a new public web endpoint is similar to adding a new Admin API endpoint for dashboard use, as shown in Working with the LiveOps Dashboard HTTP API. ASP.NET controllers in your project are assigned to either AdminApi or PublicWebApi actors depending on the controller base class you derive from, public web endpoints use PublicWebApiController.

The ServerApiBridge utility is also available to public web endpoint controllers for convenient interactions with entities. As a simple example, a public endpoint for rewarding a player from an external service could look like this:

RewardController.cs

namespace Game.Server;

public class RewardController : PublicWebApiController
{
    public class PostRewardBody
    {
        public string playerId;
        public int numGems;
    }

    [HttpPost("player/reward")] // This attribute defines the URL and type of this endpoint.
    public async Task<ActionResult> PostRewardPlayer([FromBody] PostRewardBody body)
    {
        // Check that the player ID in the request is valid and that the player exists in the database.
        EntityId playerId = await ApiBridge.ParsePlayerIdStrAndCheckForExistenceAsync(body.playerId);

        // Enqueue a synchronized server action for granting the reward
        await ApiBridge.EnqueuePlayerServerActionAsync(playerId, new PlayerAddGemsServerAction(body.numGems));
    }
}

With this controller in place, a POST request with json content

{
    playerId: Player:XXXXXXXX
    numGems: 2
}

to the URL https://game-server-public.p1.metaplay.io/player/reward would reward the targeted player with 2 gems. The implementation of the synchronized server action PlayerAddGemsServerAction is left out for brevity, see PlayerModel Server Updates for guidance on implementing server actions.

The above example would obviously be a bit too public for production use, in this form anyone could grant themselves infinite gems just be knowing the URL and their own player ID. An actual implementation would need to protect this endpoint, for example with the help of ASP.NET authorization middleware, to limit access to trusted 3rd party services.

Adding ASP.NET middleware

The SDK provides minimal functional configuration for the PublicWebApi ASP.NET server. By default public endpoints don't require authentication. To add your own configuration to the server, for example to add a custom authentication scheme for specific endpoint or path prefixes, the SDK allows overriding methods of PublicWebApiActor in your custom derived class. This is done simply by introducing the derived class in your server project:

MyPublicWebApiActor.cs

public class MyPublicWebApiActor : PublicWebApiActor
{
    public MyPublicWebApiActor(EntityId entityId) : base(entityId) {}

    protected override void ConfigureServices(IServiceCollection services)
    {
        // Instead of overriding SDK configuration, we extend it by also calling the
        // base class method.
        base.ConfigureServices(services);

        // Add a named JWT bearer token authentication scheme to be used by specific endpoints. Endpoints (controller
        // classes or individual methods) declare the authentication methods allowed by
        // [Authorize(AuthenticationSchemes = "JwtBearerScheme"])
        services.AddAuthentication().AddJwtBearer("JwtBearerScheme", options =>
        {
            options.Authority = "https://{--your-authority--}";
            options.Audience = "https://{--your-audience--}";
        });
    }
}

Relation to legacy AdminApi Webhooks

Prior to Metaplay SDK Release 32 the AdminApi web server supported additionally hosting public-facing endpoints under the /webhook path prefix. Endpoint implementations deriving from MetaplayWebhookController are run in the AdminApi web server and the /webhook prefix can be exposed as a public hostname via custom configuration of the infrastructure. For backwards compatibility this method continues to be supported but we strongly recommend migrating these endpoints to the PublicWebApi server.

The key differences are:

• AdminApi is a singleton service and therefore only runs on a single node, PublicWebApi is by default distributed across all logic nodes for automatically scaling with the size of the cluster.
• Isolating public endpoints from the admin endpoints increases security and robustness and simplifies ASP.NET configuration.
• Contrary to the legacy webhook scheme, PublicWebApi doesn't require additional infra configuration.
• AdminApi webhooks do path-based routing which complicates setting up redirect scenarios.