Tuesday 16 May 2017

Azure API Management - Add rate limiting & consuming the api (Part 4)


Introduction

This is part 4 of a series of blog posts where I will be talking about how rate-limiting is configured. We will look at the developer's perspective of the API (developer portal).

In the last post we published the "yo-blog" API via the publisher portal. The URL of the publisher & developer portal is https://mgtdemo.portal.azure-api.net/. In this post we will need to log into this portal as both:
  • An API Publisher
  • An API consuming developer (using the API)



Rate Limiting & Products

Rate limiting is tied to the "Products".

"Products" essentially refer to your API offerings. In this example we will create an API offering with the following settings.

Name  Api Testing Plan
Description Subscribers will be able to run 1 call/minute up to a maximum of 20 calls/month.
Approval Administrator approval is required.
Requires subscription Yes
Subscription Requires Approval Yes
Multiple simultaneous subscriptions No
Allowed Groups Administrators, Developers, Guests
Quota 10 calls per 10 days
Rate Limit 1 call per minute


To accomplish this, log into the publisher portal & click "Products" & click
ADD Product". Then follow the screenshots below.

Click Products & then click ADD PRODUCT

Then add the details for the new product. Then click Save.


Then click on the newly created product


Next navigate to visibility & check the appropriate visibility then save

Also, don't forget to "Publish" your APIs.


Rate limiting a product

You now need to click on policies & then click Add Policy



As you can see, a policy does not exist for the "Api Testing Plan". Click it to create one.
You then need to click the option to "Limit call rate per subscription". This should automatically set the correct XML config like so: (check next image)




After modifying the values, your XML looks like so ..

Your rate limit is 1/ per 60 seconds & quota is 10 calls per 10 days

Assign the Product to an API

You need to navigate to your API, then navigate to the Product tab & delete the "Starter" Product & add the "API Testing Plan" product.








Consuming the API

Now that the APIs have been published, lets look at what a consuming developer experiences. 

Our APIs are now published & available at the API Portal https://mgtdemo.portal.azure-api.net. When they navigate to the URL, they will see a default home page. If your API's product allows for "Guest" visibility & DOES NOT require subscription,  your API definition will also be visible. This means by default, any API linked to a "Starter" product offering will be visible without logging in.

(More to come ...)






I will be writing a series of posts to cover this topic, stay tuned ..

- Part 1: Azure API Management - An introduction 
- Part 2: Azure API Management - Your back-end api
- Part 3: Azure API Management - Creating a gateway & exposing your api
- Part 4: Azure API Management - Add rate limiting & consuming the api
- Part 5: Azure API Management - Add security

Friday 12 May 2017

Azure API Management - Creating a gateway & exposing your api (Part 3)


Introduction

This is part 3 of a series of blog posts where I will be talking about creating an Azure API Management gateway to expose a "back-end service".

In the last post I discussed a sample back-end service that we created. From the last post we now have an API definition which we can use in this post to create a gateway & expose our api. 

The url of the API definition as discussed in the last post is https://raw.githubusercontent.com/rohit-lakhanpal/azure-api-mgt-resources/master/swagger.json).

Ok then lets setup our gateway now.


Setting up an Azure API Management Gateway


Step 1: You need a resource group

To begin with you will need to create a resource group. The "back-end" service we created in the previous post will ideally be in the same resource group. 

Creating one is simple enough. Start by clicking the + icon on your azure portal & then simply follow the prompts as shown in the screenshots below:





Step 2: Add API Management to your Resource Group

To do this, navigate to the newly created resource groups & click on "Overview". You then need to click the [+ Add] icon & search for API Management. For the rest simply follow the creation wizard as shown in the screenshots below.











Once created, you should now be able to see the API Management gateway in your resource group. Click on the gateway & navigate to the overview. You should now be able to access the "Publisher" & "Developer" Portal.





Step 3: Navigating the publisher portal

As shown in the image above, open the publisher portal by clicking the "Publisher portal" link. This should open the portal in a new window which should look something like this ..

The homepage shows the dashboard view of all your apis.


When you click the "API" nav menu, it shows all available APIs. By default, an "Echo API" gets created for you. Whilst we will not be using it, lets look at all the options & settings for the echo api.
Now click the "Echo API" link

You should now be able to see the Summary page for the Echo API. As you can see, no calls have been made to the api at the moment.

The settings page lets you configure some basic details.

This is an important page. This shows all permitted operations for our api. From the screenshot above you can see that this api allows the following HTTP request methods:
GET, POST, PUT, DELETE, HEAD

API security can be set on this tab.

The "Issues" tab shows any issues that have been reported by the API's subscribers.

Now before we look at the "Products" tab, lets understand what products are & what they do?

Step 4: Understanding products

When you create any API in the portal, you can assign the API to one or many products. These products help set the the following properties to an api:
  • You can set/restrict the visibility of an API (if you need to be a registered developer on the developer portal)
  • Set weather a user is automatically appoved to use the API or requires administrator approval
  • Allow simultaneous multiple subscriptions
  • Specify which groups of users can view the API
  • List existing subscribers of an API
Now lets navigate to the products page by clicking the "Products" nav menu item.




As you can see here, the API comes built with 2 types of products; Starter & Unlimited. Lets look at the differences between the 2 products:

   Starter Unlimited
Description Subscribers will be able to run 5 calls/minute up to a maximum of 100 calls/week.  Subscribers have completely unlimited access to the API. Administrator approval is required.
Requires subscription Yes Yes
Requires subscription approval No Yes
Allows multiple simultaneous subscriptions  No No
Groups enabled to view and subscribe for this product Administrators
Developers
Guests
Administrators
Developers
Guests
Quota 100 calls per 7 days None
Rate Limit 5 calls per minute None

Now that you know the differences, lets have a look at the "Products page for the "Echo API"


This "Echo API" has both product offerings. It means that when developers sign up to the portal, they will be able to choose which product offering to which they wish to subscribe. (You will understand this better when you have a look at how to call these APIs. I will be discussing this in part 4).

Now that you've see what the Echo API is capable of, lets add our back-end APIs to this gateway.

Step 4: Add your APIs to the gateway

Now that we've had a look at the Echo API, we can import the API definition that we had created earlier as shown below. All we need is the API definition file we created using Swagger (from part 2). 

Click the "Import API" link

Select the options to Import API from URL & enter the URL of your API definition. In our case, the definition used is a swagger file. 

Select the New API  radio button.

Add the Web Api URL suffix.

Select the Protocols required & click Save.

Now your API should be ready to use. Click on the API to look at the details.


As you can see from the Settings page, most of the details are already filled for you.

The operations have also been imported.


We will now make this API available as a part of the "Starter" product. To do this, click "Products" as shown below.
Now click Add Products

Now check Starter and then click Save


Your API is now available to developers as a part of the "Starter" package.


Now that we have published this API, in the next post we will explore how rate-limiting is configured. We will look at the developer's perspective of the API (developer portal).





I will be writing a series of posts to cover this topic, stay tuned ..

- Part 1: Azure API Management - An introduction 
- Part 2: Azure API Management - Your back-end api
- Part 3: Azure API Management - Creating a gateway & exposing your api
- Part 4: Azure API Management - Add rate limiting & consuming the api
- Part 5: Azure API Management - Add security

Monday 1 May 2017

Azure API Management - Your back-end api (Part 2)


Introduction

This is part 2 of a series of blog posts where I will be talking about exposing your back-end apis via Azure API Management as production ready apis.

In this post I will discuss a sample scenario that we will use throughout this series to explore the capabilities of the platform. 

Lets look at the following sample scenario.

Sample Scenario

I have an existing "Back-End-Service" that you wish to serve up via Azure API Management. This service essentially exposes user, post & comment data related to a blogging site. It's called "Yo Blog". 

I have made this "Back-End-Service" publicly accessible (http://52.175.244.3:8080) but in a realistic scenario this would be hidden in a private network with some form of security on top of it. If you would like to follow along, you can create your own serve as shown here https://github.com/rohit-lakhanpal/azure-api-mgt-resources.

As you can see, the following REST endpoints are exposed: 

User Related Operations: Operations about user
Operation
Description
Fetch a list of all users
Create user
Find user by ID

Post Related Operations: Operations about blog posts & comments
Operation
Description
Fetch a list of all posts
Create post
Find post by ID
Find comments by post ID


An API Definition

Based on the "Back-End-Service" that you are planning to expose, you  now need to create an API definition. This is something that we will be using in the next stage to add 

I have created an API definition using Swagger. This is accessible at https://raw.githubusercontent.com/rohit-lakhanpal/azure-api-mgt-resources/master/swagger.json (Note: If you have created your own API, you will need this link before the next step.)





I will be writing a series of posts to cover this topic, stay tuned ..

- Part 1: Azure API Management - An introduction 
- Part 2: Azure API Management - Your back-end api
- Part 3: Azure API Management - Creating a gateway & exposing your api
- Part 4: Azure API Management - Add rate limiting & consuming the api
- Part 5: Azure API Management - Add security


Thursday 27 April 2017

Azure API Management - An introduction (Part 1)



Is there an API for that?

If you've worked for a SaaS vendor, I'm fairly certain that at some point you've been asked this question. For most apps today, integration is no longer a should-have but a must-have requirement.

As a developer we love writing amazing json:api compliant REST endpoints that expose app functionality BUT we often neglect the realities of hosting these endpoints in a production-ready state.

This is where Azure API Management comes in. Here's the pitch from Microsoft:

Azure API Management as a turnkey solution for publishing APIs to external and internal customers. Quickly create consistent and modern API gateways for existing back-end services hosted anywhere, secure and protect them from abuse and overuse, and get insights into usage and health. Plus, automate and scale developer on-boarding to help get your API program up and running. 

What is it?

  • Serves as a proxy that sits between your back-end services/apis & the calling apps
  • Essentially a common facade on top of existing apis
  • This "intermediate layer" allows you to quickly create consistent and modern API gateways for existing back-end services hosted anywhere
  • Turnkey solution for publishing apis to external and internal consumers.

Why use Azure API Management?

  • Perfect way to easily package & publish your existing back-end apis
  • Allows easy developer on-boarding (serves as a self-service portal)
    • Ramp-up uptake with docs, samples & an api console
    • Provide API documentation and an interactive console
    • Allows API discoverability
  • Enhance back end services by
    • Throttle, rate limit and quota your APIs
    • Monitor health of your APIs and quickly identify errors
    • Gain analytic insights on how your APIs are being used
  • Allows managing your service via the Azure portal, REST API, PowerShell, or Git repository



Tuesday 14 February 2017

An introduction to the Microsoft Bot Framework



Today was Day One of the Microsoft Ignite Australia event held in sunny Gold Coast that 2 of my colleagues & I got the chance to attend.

I loved the sessions around the Microsoft Cognitive Services & the Microsoft Bot Framework which inspired me to write my first bot.

What are bots?

Bots are simply applications that perform automated tasks. A simple example is a chatbot. An interesting example of such a bot is "Dom the pizza bot". Instead of calling up or ordering online, customers will be able to simply message Dom, the Domino’s pizza bot, and request food with a single world or emoji.


Even Cortana or Siri are example of such bots. Clearly showing how bots are the way of the future!

How do these bots communicate you ask?

Most use-cases for bots include instances where bots are communicating with users & providing insights without any specific human intervention. 

The medium through which these bots communicate are called "Channel(s)". 

At the time of writing this article, the following channels are supported by the Microsoft Bot Framework:
  1. Skype (auto-configured)
  2. Microsoft Teams
  3. Web Chat (auto-configured, embeddable)
  4. Direct Line (API to host your bot in your app)
  5. Office 365 mail
  6. Facebook Messenger
  7. GroupMe
  8. Kik
  9. Slack
  10. SMS via Twilio
  11. Telegram

Make sure to look at the live list here.

What can I do with these bots?

When you combine the power of using the Microsoft Bot Framework via the aforementioned channels AND Microsoft's Cognitive Services APIs, you can make some really kick a$$ bots.

FYI, if you haven't heard of Microsoft's Cognitive Services, they're some super funky APIs and services available to developers to make their applications more intelligent, engaging and discoverable. 

Microsoft Cognitive Services expands on Microsoft’s evolving portfolio of machine learning APIs and enables developers to easily add intelligent features – such as emotion and video detection; facial, speech and vision recognition; and speech and language understanding – into their applications. Check this out for more info. https://www.microsoft.com/cognitive-services/en-us/documentation.


Your first bot

So to begin with, you can build a super simple greeting bot. You say hello, and it greets you back. Begin by logging into azure and creating a new Bot Service.

Click the + icon & search for "Bot Service"

Click "Create"

Add an "App name" & select or add a "Resource Group" and click "Create"
Now remember, unless you selected the option to "Pin to dashboard" your bot will not appear on your dashboard. As you can see that I forgot to pin it, I should be able to view my bot in my notifications. Click the notifications icon (highlighted in red) & then click the relevant notification.


In order to authenticate your bot with the Bot Framework, you'll need to register your application and generate an App ID and password. 

Click the button to "Create Microsoft App ID and password"
This should open up a new window that helps you generate an App ID and password.
Click the "Generate an app password to continue" button

A new popup with your password will now appear. REMEMBER TO COPY THIS PASSWORD SOMEWHERE.

You can now click the "Finish and go back to Bot Framework" button
When you go back, your App ID will be pre-filled & you will need to paste your password in the relevant slot.

Remember to paste your password in


You now get to choose a language for your bot. My C#'s a tad better than my node but to show you show simple this really is, I'm choosing NodeJS. Use the "Basic" template to create a bot. Remember to click the "Create Bot" button at the bottom of the page.

Choose "NodeJS" and select the "Basic" template and click "Create Bot" at the bottom of the page

Your bot will be created in a few .. (ok quick, 1 min dance party https://youtu.be/ULC2C3VjO-o)





Once your bot is created, it should spit out the templated code. You should already be able to play with the templated code in the chat window. I have highlighted a key method here. 



You can be as silly and creative as you'd like.


Select channels to add it to one of the available channels. I'm going to add it to my Microsoft Teams.

Check out the available channels and add the ones you want by clicking "Add"

Add it to teams if you want



When you're ready, you can go to public with your bot, by navigating to settings and adding your bot details.


You can then navigate to publish and add the necessary details if you'd like to publish your bot.


Your bot

You can also navigate to the Microsoft Bot Framework dev site & view your bots here:

Log in with your standard credentials & click "My Bots"







My bot in action

By clicking the "Add to Skype" button this should open your Skype. Here's the bot in action on skype.





Easy-peasy huh? If you'd like to know more I've to some more useful links for you here:
https://app.pluralsight.com/library/courses/microsoft-bot-framework-getting-started/table-of-contents