Tag Archives: Azure API Management

Thick API Gateways

Posted on by

I came across the term ‘Overambitious API Gateways’ from Thought Works tech radar. The point is, whether is it good or bad to have business logic in the API Gateways? Since the term Gateway is not a functional requirement and serves the purpose of a reverse proxy; it is quite obvious that including business logic in an API gateway is NOT a good design. But the idea behind the overambitious API gateways, seems to be a finger pointing at the API Gateway vendors, rather than considering the solution design and development and how the API Gateways should be used.

I prefer the term ‘Thick API Gateways‘ over overambitious API Gateways because the implementation is up to the developer regardless of what the tool can offer. This ensures an anti-pattern.

With the advent of microservices architecture, API Gateways gained another additional boost in the developer tool box, compared to other traditional integration technologies.

giphy

Microservices favor the patterns like API composer (aggregation of results from multiple services) Saga (orchestration of services with compensation) at the API Gateway. API Gateways also host other business logic like authorization, model transformation and etc. resulting a Thick API Gateway implementations.

Having said, though thick API gateway is a bad design and brings some awkward feeling at night when you sleep, in few cases it is quite inevitable. If you’re building a solution with different systems and orchestration of the business flows is easy and fast at the API gateway. In some cases it is impossible to change all the back-end services, so we should inject custom code between the services and API gateways to achieve this, which would result other challenges.

At the same time, as developers when we get a new tool we’re excited about it, and we often fall into the ‘if all you have is a hammer, everything looks like a nail‘ paradigm. It’s better to avoid this.

giphy1

Let’s see some practical stuff; in fact, what kind of business logic the modern API gateways can include? For example, if we take the gateway service offered in Azure API Management (APIM), it is enriched with high degree of programmable request/response pipeline.

Below APIM policy, I have provided an authorization template based on the role based claims.

The API gateway decides the authorization to the endpoints based on the role based claims. The sections are commented, first it validates the incoming JWT token, then sets the role claim in the context variable and finally handle authorization to the endpoints based on the role claim.


<policies>
<inbound>
<!– validates RS256 JWT token –>
<validate-jwt header-name="massrover_token" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized"
require-expiration-time="true" require-signed-tokens="true">
<audiences>
<audience>audience id</audience>
</audiences>
<issuers>
<issuer>issuer id</issuer>
</issuers>
<required-claims>
<claim name="role" match="any">
<value>admin</value>
<value>moderator</value>
<value>reader</value>
</claim>
</required-claims>
<openid-config url="https://massrover.idenityserver/.well-known/openid-configuration" />
</validate-jwt>
<!– sets the role claim to the context variable –>
<set-variable name="massrover_role"
value="@(context.Request.Headers["massrover_token"].First().Split(' ')[1].AsJwt()?.Claims["role"].FirstOrDefault())" />
<!– performs authorization based on role claim and allowed http method –>
<choose>
<when condition="@(context.Variables.GetValue("massrover_role").Equals("admin"))">
<forward-request/>
</when>
<when condition="@(context.Variables.GetValue("massrover_role").Equals("moderator")">
<when condition="@(context.Request.Method.Equals("delete", StringComparison.OrdinalIgnoreCase))">
<return-response>
<set-status code="403" reason="Forbidden" />
<set-body>Moderators cannot perform delete action</set-body>
</return-response>
</when>
<otherwise>
<forward-request/>
</otherwise>
</when>
<when condition="@(context.Variables.GetValue("massrover_role").Equals("reader")">
<when condition="@(context.Request.Method.Equals("get", StringComparison.OrdinalIgnoreCase))">
<forward-request/>
</when>
<otherwise>
<return-response>
<set-status code="403" reason="Forbidden" />
<set-body>Readers have only read access</set-body>
</return-response>
</otherwise>
</when>
<otherwise>
<return-response">
<set-status code="405" reason="Not Allowed" />
<set-body>Invalid role claim</set-body>
</return-response>
</otherwise>
</choose>
<base />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
</policies>

view raw

jwt claims based authorization.xml

hosted with ❤ by GitHub

Note: This is a thick API gateway implementation and the pros and cons of this is subject to the problem in hand. This above is a practical elaboration of one thick API implementation.

Project Oxford – Behind the scenes of how-old.net

Posted on by

http://www.how-old.net has been trending recently in social media. Simply you can upload a picture in this website and it will detect the faces in the photo and tells you the gender and the age of the person the face belongs to.

The site uses Face API behind the scenes, which is available here http://gallery.azureml.net/MachineLearningAPI/b0b2598aa46c4f44a08af8891e415cc7

You can try this service by subscribing to the service. It’s an App Service in Microsoft Azure and you need to have a Azure subscription to subscribed to that. Currently it is free and you are allowed to make 20 transactions per minute for the subscription.

image

image

Once you are done with the purchase like any other service Face API is available in the Azure Marketplace section.

image

In the management section you can get the key for the API, the Face API is managed by Azure API Management (read more about Azure API Management here)

 

image

Face API teams also provides a sample WPF application with the portable client library as a wrapper for their REST service.

Getting Started with the Face API .NET client SDK

A simple face detection method would be very similar to this.

var faceClient = new FaceServiceClient("<your subscription key>");

                        var faces = await faceClient.DetectAsync(fileStream, false, true, true, false);

                        var collection = new List<MyFaceModel>();

                        foreach (var face in faces)
                        {
                            collection.Add(new MyFaceModel()
                                {
                                    FaceId = face.FaceId.ToString(),
                                    Gender = face.Attributes.Gender,
                                    Age = face.Attributes.Age
                                });
                        }

A direct JSON output would be like this. (test it here – http://www.projectoxford.ai/demo/face)

image

Face detection is made immensely easy by this research project. 🙂 Happy face detection.

The library has loads of other features like matching faces, grouping highlighting and all.

Microsoft Azure API Management Policies

Posted on by

This is the second post of the Microsoft Azure API Management tutorial. See the first post – Introduction to Microsoft Azure API Management. This post describes about the advance

Policies define the rules for the incoming and outgoing API requests. See this link for the full API Management Policy Reference. Different policies are applied at different levels of the API Management. In order to define a policy go to Policies tab, select a Product or a API or an Operation based on what the policy could be applied, then drag and drop the policy template and fill the parameters. (I think Microsoft Azure will come with a good UI for doing this in the near future).

For example I’ve explained how to create a policy to limit the number of calls to the API. I have the same API I explained in the previous post – Introduction to Microsoft Azure API Management. Go to Policies tab select the Product and in the right hand side you will the list of policies. Since you we haven’t configured any policies yet the work area will ask you to create a policy for the API. Click ‘Add Policy File’. Then click on the <inbound> section of the XML. The position of the cursor is important based on which policy you want to add; in this sample we’re adding a call limiting policy then its obvious we should add in in the inbound section of the XML if you keep the cursor in other areas and try to add the call limiting policy the interface will react numb. Unfortunately if won’t tell you what’s wrong but simply you cannot add the policies. API Management Policy Reference will guide you get the knowledge about the usage of the policies.

Call Rate Limiting Policy

Capture

Once the policy is added you can see the policy template and it’s a matter of filling the blanks. Notice that this policy is applied in the Product level in the configuration, but it provides the granularity to control the calls to Operations level in the XML. I have added few inputs and the final policy looks like the following.

defined policy

The XML template is self descriptive. Here I have mentioned that only 10 calls could be made in 60 seconds from one subscriber (from one subscription key). And in that 10 calls Nebula Customers API  would handle 6 and again even those 6 calls are equally divided to 2 Operations. After editing the template we save the configuration. Then let’s check that in the Developer Portal.

too many requests

See the response when I try to make the 4th call to the operation it says me to wait for some time. I personally prefer this error message because it’s very helpful and developers can easily hook up any automatic retry call with an accurate timer event rather than randomly polling the service.

Content Serialization

Now let’s check another policy; notice that the API Management outputs the content in JSON as it is the default content format of our backend service. Suppose if I need the format in the XML  I can use the ‘Convert JSON to XML’ policy. Make additional note here that this policy could be applied at API or Operations scopes. So we should select the API and create a new policy configuration.

image 

Since I have applied this policy at the API level all the Operations in the API will return XML. Let’s check that by invoking the same Operation we invoked in the previous scenario and we get the response in XML as expected.

image

There are plenty of Policies available as templates including CORS access, IP restriction and others. Try different policies to get know them better in the implementation. I think soon Microsoft Azure team will come up with a new user interface for the Policy management.

Introduction to Microsoft Azure API Management – Step by Step tutorial

Posted on by

Introduction to API Management

Microsoft acquired a company named Apiphany last year (read about the acquisition) and jumped to the API Management market. So what is API Management ? Given below is the definition what Google gives for the question; indeed it’s a fairly well descriptive definition.

imageMicrosoft Azure API Management is backed by the compute and the storage of Microsoft Azure. Rest of the post explains how to get started with the API Management.

 

Getting Started with Microsoft Azure API Management

Login to the Microsoft Azure portal, go to API Management and create a API Management service. In the first screen of the wizard you have to specify the URL, select the subscription (if you have more than one) and the region.

image

In the next screen you enter your organization name and the administration email. (you can simply enter your personal email here it doesn’t need to be the one with your organization domain specific one. I used my hotmail id).

image

In this screen you can select for the advance settings, which opens the third wizard panel. There you can select the tier. There are two tiers available; Developer and Standard. Default selection is Developer tier.

See the difference between the tiers : http://azure.microsoft.com/en-us/pricing/details/api-management/

Now the API Management service has been provisioned.

image 

Creating APIs

Click on the arrow icon and get inside the service, then click on the Management Console. By default when you create a Azure API Management service it creates a sample API known as Echo API and sample Product. I deleted all the auto generated default APIs and Products and this article walk you through from the scratch.

API Management requires a back end service, which is our real web service we want to expose via API Management to developers. I created a simple REST service using Web API and hosted it in the Azure Websites. The URL http: //nebulacustomers.azurewebsites.net/ 

With those information we can now start using Azure API Management. First we have to create a API. In the management console click on APIs and create one.

image

Enter the name of the API and the web service URL. Web API URL suffix is a URL suffix which is to group and categorize the service endpoint as you create many APIs. It is optional but good to have because that will make your life easier as your number of APIs grows. By default HTTPS is selected.

 

Adding Operations

Technically speaking operations are trigger points of the web service in the API Management. Click on the API we created (Nebula Customers) and select the Operations tab and click on ADD Operation.

image

Here we can create operations and point them to our backend web service. Many operations can point to a single endpoint in our backend service. In my backend service I have only two endpoints.

http: //nebulacustomers.azurewebsites.net/api/customers – List of customers

http: //nebulacustomers.azurewebsites.net/api/customers?name=<name> – Gets the specified customer object.

We create 3 operations, two of them will point to the first endpoint and the last one will point to the endpoint with the name parameter.

Create three operations as follows.

Operation to list the customers

  • HTTP Verb – GET
  • URL Template – /customers
  • Rewrite URL Template – /api/customers
  • Display Name – List of customers

Operation for the cached customers

  • HTTP Verb – GET
  • URL Template – /cachedcustomers
  • Rewrite URL Template – /api/customers
  • Display Name – List of customers
  • And go to Cache tab and check the Enable.

Note that above 2 operations are pointing to the same endpoint in our backend service as the rewrite the URL templates are same. Here caching is done by the API Management and our backend service isn’t aware of it.

Third operation to get the customer with the specified name.

  • HTTP Verb – GET
  • URL Template – /customers/{name}
  • Rewrite URL Template – /api/customers?name={name}
  • Display Name – Get the customer by name

After adding all three operations you will have a similar screen like this.image

Creating Products

Now we have our API and operations, in order to expose the API to developers as packed module we should create a Product and associate the API to it. One Product can have many APIs. Developers who subscribe to a Product get access to the APIs associated with the Product.

Go to Product tab and create new Product.

image In this screen check the “Require subscription approval” if you need to get email requests for approving the subscription requests. You have to configure this email address in the notification section. Second checkbox “Allow multiple simultaneous subscriptions” allows the developers to create more than one subscription for the product. Each subscription is identified by a unique key and in this option you also can specify the maximum number of simultaneous subscriptions.

After creating the Product click to open that and associate the APIs to the Product. Click in ADD API to Product.

image

Go to Visibility tab in the product section and check Developers. Developers need to authenticated themselves in the Developer Portal, subscribe to Products and obtain subscription keys in order to use the API. Guests are unauthenticated users who allowed to view the APIs and operations but not to call them. Administrators are the people who create and manage APIs, Operations and Products.

After enabling the visibility to developers Publish the product in order to make it available in the Developer Portal.

 

Developer Portal

Now the API is built and published, now it’s the developers work to deal with the Developer Portal and subscribe to the product. Click on the Developer Portal link in on the right hand top corner. When you’re working as the administrator and click on the Developer portal you are logged into the Developer portal as administrator.

image

The above is the default view of the Developer Portal. You can do branding on the portal if required.

Go to Products and you can see the Product we created and as an administrator you’re already subscribed to this Product. So click on the APIS tab click on the specific API.

image

Click in the List of Customers operation and click on the Open Console in order to check test the service.

image 

Click on th HTTP GET and invoke the service. The above URL is the full URL with the subscription key. Response comes in JSON (as this is the default of my backend service).

image 

Now invoke the List of cached customers and check the response time.

First call it took 402ms.

image

Second call took only 15ms.

image

 

 

Similarly invoke the Get customer by name specifying a parameter. The coolest part of the Developer Portal is that it’s really helpful for the developers to test the endpoints and also it generates the code in may languages on how to consume those endpoints. Below is the code generated in Objective C for consuming the customer name endpoint.

image

 

Conclusion for the Introduction

Now our API Management service is working perfectly. We can control the input and output of the service in more granular ways using policies. We can configure notifications, customize email templates, security, assigning different identity management of developers and much more. These things I will cover in the API Management Advanced tutorial on another blog post.

If you want to try the exact demo I’ve explained here you need the exact backend service. You can download it here. (requires Visual Studio 2013)