DEV Community: Olcay Bayram

Architect Azure API Management service

Olcay Bayram — Fri, 31 Jan 2020 14:12:11 +0000

Let's setup an API gateway using the Azure API Management service with a nice architecture.

An API gateway is positioned between your APIs and the Internet. You can control how the APIs are exposed or limit the usage per subscription through the Azure portal.

Why would I use the Azure API Management service?

It is a native Azure SaaS (software as a service) which brings nice pros;

API documentation
Rate limiting access
Health monitoring
Modern formats like JSON
Connections to any API
Analytics
Security
Built-in caching
Network tracing

Is there any trade-off?

Yes, the circuit breaker policy is not implemented yet. You can build your own API gateway with a circuit breaker using third-party libraries like Ocelot and Polly with Quality of Service configured but does it worth to go down to a PaaS (platform as a service) instead of a SaaS?

Setup an API Management service

Sign into the Azure portal.
Create a resource through Integration, and then API Management.
Give a globally unique name to your resource.
Select Consumption (99.9SLA, %) as the pricing tier because this serverless plan is much faster to create for an ad-hoc testing.
Click Create.
Deployment will start and it may take several minutes.

When the deployment is complete you will get a notification email to the address you provided as an administrator. Once it is deployed we import our first API.

Import an API

Sign into the Azure portal.
Go to All Resources, and then select your API gateway.
Under API Management, click APIs
Choose your specification. If you are using Swashbuckle library in your API that means you already have OpenAPI specification.
On the Create from OpenAPI specification page, paste the swagger JSON URL of your API. The other fields will be populated according to your API.
Click Create.

Now, you can test the gateway through the Test tab on the API details page.

Subscriptions

A subscription is like authenticating a client with a public key which can be transferred through in the headers or in the query string. The subscription can be scoped to All APIs, a single API or a group of APIs (called a product).

The unique subscription keys can be regenerated at any time. Every subscription has two keys, a primary and a secondary to avoid downtime.

The default header name is Ocp-Apim-Subscription-Key, and the default query string is subscription-key. If the key is not passed in the header, or as a query string in the URL, you'll get a 401 Access Denied response from the API gateway.

Policies

In Azure API Management, administrators can use policies to alter the behavior of APIs through configuration. Policies execute at four different times:

Inbound: These policies execute when a request is received from a client.
Backend: These policies execute before a request is forwarded to a managed API.
Outbound: These policies execute before a response is sent to a client.
On-Error: These policies execute when an exception is raised.

There is one more scope in addition to subscription scopes for policies and it is operation policy scope. We can determine order of the policies. If we place <base /> tag before a policy that means higher policies will be applied first and vice versa.

Commonly used policies

Check HTTP header
Limit call rate by subscription
Restrict caller IP's
Authenticate
CORS
JSONP
Convert XML to JSON
Rewrite URL

Cache policy

By caching the compiled responses we can reduce processing time in our APIs and respond faster. We can add an outbound policy to cache the responses and an inbound policy to check if there is a cached response for the current request. You can see these two policies in the example below which is using a vary-by-query-parameter tag to store separate responses per id in a query string:

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false"
        downstream-caching-type="none"
        must-revalidate="true" caching-type="internal">
            <vary-by-query-parameter>id</vary-by-query-parameter>
        </cache-lookup>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <cache-store duration="60" />
        <base />
    </outbound>
    </on-error>
        <base />
    </on-error>
</policies>

The vary-by-developer attribute is separating responses according to the subscription key.

As you can already notice, the caching type for this example is internal. We can use an external caching service as well.

Add an external cache

Create an Azure Cache for Redis resource.
Go to your API Management service and click External cache under Settings and then click + Add.
Choose your Redis cache instance and a location to use from. The other fields will be populated.
Click Save.
Go to APIs under API Management an then select the API and click the pencil next to the cache-lookup to edit the policy.
Change caching type from Internal to External

You can test your API in the Test tab to see if it is giving unchanged results.

Remove unnecessary info from response header

ASP.NET add a X-Powered-By: ASP.NET header to our APIs by default but this could allow a malicious user to attempt to exploit any bugs known for the technology stack. We can remove this header from a response by adding set-header policy to outbound as in the example below;

<outbound>
   <set-header name="X-Powered-By" exists-action="delete" />
   <base />
</outbound>

Replace content with a transformation policy

If we build an API with the HATEOAS constraint, that means we have links in the responses. Since the gateway is overriding the URLs, we may need to replace the links in the response body. We can do it by adding <redirect-content-urls /> tag to the <outbound> element as below;

<outbound>
   <set-header name="X-Powered-By" exists-action="delete" />
   <redirect-content-urls />
   <base />
</outbound>

Limit call rate by subscription

If we place the rate-limit-by-key tag inside the inbound element, it will limit the call rate by subscription. A subscription can call this API 10 times in 60 seconds and only the successful responses are counted.

<inbound>
    <rate-limit-by-key calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Subscription.Id)"/>
    <base />
</inbound>

Validate a certificate to allow requests

If we want to use certificate authentication in our API gateway, we can validate it by an inbound policy.

Under Settings, click Custom domains in your API Management service.
Toggle Yes for the Request client certificate option, and then click Save.
Replace the <inbound> node of the policy file with the following XML, while replacing desired-thumbprint part with your certificate thumbprint;

<inbound>
    <choose>
        <when condition="@(context.Request.Certificate == null || 
        context.Request.Certificate.Thumbprint != "desired-thumbprint")" >
            <return-response>
                <set-status code="403" reason="Invalid client certificate" />
            </return-response>
        </when>
    </choose>
    <base />
</inbound>

Please, write the policies that you find useful in the comments.

Azure Durable Functions

Olcay Bayram — Fri, 31 Jan 2020 10:56:27 +0000

Durable Functions is an extension of Azure Functions that enables you to perform long-lasting, stateful operations in Azure. Azure provides the infrastructure for maintaining state information. You can use Durable Functions to orchestrate a long-running workflow. Using this approach, you get all the benefits of a serverless hosting model, while letting the Durable Functions framework take care of activity monitoring, synchronization, and runtime concerns.

Suppose your e-commerce company has a warehouse and there is a staff to ship products. We want to automate the process, but still involve humans. We can implement human interaction pattern by using an orchestrator function. The orchestrator uses a durable timer to request approval. The orchestrator escalates if timeout occurs. The orchestrator waits for an external event, such as a notification that's generated by a human interaction.

Create a function app project

If you did not create a function app on Visual Studio before, please follow the steps on Create your first durable function in C#.

Copy the code below to your function.cs file.

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace OlcayFunctionAppSample
{
    public static class DurableFunction
    {
        [FunctionName("DurableFunction_Orchestrator")]
        public static async Task<List<string>> RunOrchestrator(
            [OrchestrationTrigger] DurableOrchestrationContext context)
        {
            var outputs = new List<string>();

            using (var timeoutCts = new CancellationTokenSource())
            {
                DateTime expiration = context.CurrentUtcDateTime.AddSeconds(20);
                Task timeoutTask = context.CreateTimer(expiration, timeoutCts.Token);

                Task shipTask = context.WaitForExternalEvent("Event_Ship");

                // Wait until one of the tasks is completed
                Task winner = await Task.WhenAny(shipTask, timeoutTask);
                if (winner == shipTask)
                {
                    // Event raised
                    outputs.Add(await context.CallActivityAsync<string>("DurableFunction_Ship", "shipped"));
                }
                else
                {
                    // Timeout expired
                    outputs.Add(await context.CallActivityAsync<string>("DurableFunction_Escalate", "Head of department"));
                }

                if (!timeoutTask.IsCompleted)
                {
                    // All pending timers must be complete or canceled before the function exits.
                    timeoutCts.Cancel();
                }
            }

            return outputs;
        }

        [FunctionName("DurableFunction_Ship")]
        public static string Ship([ActivityTrigger] string activityInput, ILogger log)
        {
            log.LogInformation($"The order is {activityInput}.");
            return $"The order is {activityInput}!";
        }

        [FunctionName("DurableFunction_Escalate")]
        public static string Escalate([ActivityTrigger] string activityInput, ILogger log)
        {
            log.LogInformation($"The order is escalated to {activityInput}.");
            return $"The order is escalated to {activityInput}!";
        }

        [FunctionName("DurableFunction_HttpStart")]
        public static async Task<HttpResponseMessage> HttpStart(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")]
            HttpRequestMessage req,
            [OrchestrationClient] DurableOrchestrationClient starter,
            ILogger log)
        {
            string instanceId = await starter.StartNewAsync("DurableFunction_Orchestrator", null);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

            return starter.CreateCheckStatusResponse(req, instanceId);
        }
    }
}

Test the function locally

Press F5 to start debugging.
Copy the URL of your function from the Azure Functions runtime output.
Paste the URL http://localhost:7071/api/DurableFunction_HttpStart into your browser's address bar and execute the request.
Copy the URL value for statusQueryGetUri and paste it in the browser's address bar and execute the request. If you do it on time, you will see Pending or Running as runtimeStatus.
If you wait enough to expire timeout task and refresh, the runtimeStatus would be Completed and an output message would be displayed as The order is escalated to Head of department!.
If you raise ship event before the timeout expires, the runtimeStatus would be Completed and an output message would be displayed as The order is shipped!.

Raising an event

Copy the URL value for sendEventPostUri, replace {eventName} with Event_Ship and run the command below with the the URL on command prompt.

curl --request POST 'http://localhost:7071/runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/Event_Ship' \ --header 'Content-Type: application/json' --data-raw ''