Businesses everywhere are looking to extend their operations as a digital platform, creating new channels, finding new customers, and driving deeper engagement with existing ones. Now, with the API Management (APIM) and Web PubSub service (AWPS), you are able to expand the real-time messaging capability of your application with a consistent and modern API gateway.

• Build apps faster and deliver immediate value to your customers through API-first approaches.
• Transform your legacy services into modern REST-based APIs or WebSocket APIs.
• Consistent experience to manage APIs (REST and WebSocket) across clouds and on-premises.

Let’s go through the key steps together and learn how to implement this reference solution:  

• Create the Azure Web PubSub Service
• Create the Azure API Management service and configure the WebSocket rules
• Update a Web PubSub sample to use the created Azure API Management

Setup Web PubSub

1. Follow the steps to create your Web PubSub service which we refer to as AWPS1 in the following sections.
2. When created, go to the Keys tab for the resource from the Azure portal, and you can see the hostname and connection strings of your resource. There is also a Client URL Generator tool in the portal that it can generate some temporarily valid URLs for your WebSocket clients to connect to. Let's use this tool to generate an URL for our demo with a hub called demoHub. This tool is for quick test purposes only, we also provide APIs in various languages to generate the URL for production usage, for example, WebPubSubServiceClient.GetClientAccessUri Method for .NET.
3. Copy the generated Client Access URL for later use. Let's have a quick look into the Client Access URL, it contains:
   • the hostname of the Web PubSub service xxx.webpubsub.azure.com with wss scheme,
   • and the path containing the hub name /client/hubs/demoHub,
   • and a query parameter access_token which is the JWT token that the Web PubSub service uses to validate and authenticate the WebSocket clients. 

Setup API Management

1. Follow the steps to create your API Management service which we refer to as APIM1 in the following sections.
2. When created, go to the APIs tab for the resource from the Azure portal, click Add API and choose WebSocket

3. Create with the following parameters:

   • WebSocket URL: wss://<your_webpubsub_name>.webpubsub.azure.com/client/hubs/demoHub
     • Replace <your_webpubsub_name> with the name of your AWPS1
   • API URL suffix: ·client/hubs/demoHub·

4. Now you are all set, select the API and use the Test tab to test the connection.

   1. Remember the access_token query parameter we get from the AWPS1 Client Access URL? Paste it here as the access_token query parameter, and Connect.
   2. You can now see in the output Connected

Try samples

Let's update this publish and subscribe message sample to use APIM1, the only thing to change is to let the WebSocket subscriber connect to APIM1 instead.

After the subscriber gets the full URL to connect to AWPS1, let's update the URL to connect to APIM, and don't forget to append the subscription-key query parameter if your APIM settings enabled it.

For example, in C#, update the code as below:

static async Task Main(string[] args)
{
    // ...

    var serviceClient = new WebPubSubServiceClient(connectionString, hub);
    var url = serviceClient.GetClientAccessUri();

    // Replace the Host with APIM1's, and append APIM1's subscription-key query parameter if it is enabled
    var urlBuilder = new UriBuilder(url);
    // Replace the hostname with APIM's
    urlBuilder.Host = "<APIM1_host_name>.azure-api.net";
    // Get the subscription-key if you enabled it in APIM portal
    var subscriptionKey = "<the_subscription_key>";
    var subscriptionKeyQuery = $"subscription-key={subscriptionKey}";
    urlBuilder.Query = string.IsNullOrEmpty(urlBuilder.Query) ? subscriptionKeyQuery : $"{urlBuilder.Query}&{subscriptionKeyQuery}";
    var apim1Url = urlBuilder.Uri;
    // Start the WebSocket connection
    using (var client = new WebsocketClient(apim1Url))
    {
        // ...
    }
}