December 16, 2016

API Management in Azure using Microsoft's solution - API-first design

This is a series of posts regarding the topic of API's and API Management on Microsoft Azure. Not all posts in this series are directly related to Microsoft Azure and their implementation of API Management, that is intentional. The series also explains about API's, about creating API's and about what it construes to in order to manage them, conceptually and in reality. The reason for this series is that over the past 12 months I've come across many articles on the web, have been in many discussions and advised various clients of mine on this topic. Sometimes discussing with fellow architects, other times with vendors, still other discussions where with developers and managers. But the overall situation has always been that none of the people at the other side of the table had a full grasp of what developing API's in an organisation means, what it entails to manage them or what should be worried about when deciding to go API. I hope you enjoy reading these articles, and when you feel like it, comment on the articles. I always take serious comments serious and will reply to my best effort.


API's are about the hardest thing to create in software engineering. Designing software to act as an API before anything else is even harder.

There's a new buzz going around in IT; API Management, and everything associated with it. I think it's even more buzzy than Microservices. Especially with shout-outs like "API First", compared to "Cloud First", "Mobile First" and "Web First" of yesteryear, we need to be cautious about what this means. This post is not about what API's are, why you should develop API's, or why API development is probably the hardest area in software development in this day and age. This post is about how you should look at Microsoft's offering on API Management and how to use it. Not the definitive guide, but a guideline instead.

This post is focusing on the API-first buzzzzzz...

Microsoft Azure

Skip to the next section when you're not interested in a view of mine on Azure, otherwise keep reading.
Whatever you think about Amazon AWS and the incredible pace by which Dr. Werner Vogel and his team is telling the world what The Cloud is and will be, you have to agree that the more amazing player in the Cloud arena at this point in time is arguably Microsoft.
Amazon has a track record of providing an amazing experience to their customers, both at but also on AWS. Clearly considering what the customer wants and doing everything to make the customer want to spend more money with them then anywhere else. They're doing this for over a decade now. I would argue that AWS is for those that understand the Cloud. Microsoft is arguably only since about 5 or 6 years a Cloud player to consider. Although announced in 2008, their implementation of the Cloud was in early 2010 and called Microsoft Azure in 2014. It really matured in 2016 with proper RBAC (Role Based Access Control) and proper infrastructure-in-code capabilities through the Azure Resource Manager. Other than AWS, which is a true 'API first' and 'Automate everything' platform, Azure is only since recently truly catching up in allowing everything to be done through API's and automation. Which is too bad since one of the Cloud's most awesome traits is the virtually infinite amount of resources allowing to provision and deploy a virtually infinite amount of versions of an application. Anyway, Microsoft's lack of API's and automation capabilities in the Cloud is consistent with its desktop platform Windows, which is a point-and-click affair instead of a scripting affair. Even administrators on Windows will use the point-and-click interface instead of the CLI (Command Line Interface) which is so accustomed to their Unix and Linux colleagues. It makes the platform less intimidating and many of the hard work is hidden behind a button and some checkboxes. This is how the Cloud is managed as well, through a Portal. It's a "point-and-click first" philosophy it seems. And many of the customers of Azure are happy with this. Who wants to be intimidated by a computer after seeing 2001 and Terminator anyway?

Setting AWS and Azure side-by-side one might see the following key difference: AWS allows you to do IT like playing with Lego. Amazon started with the basic building blocks. The Lego of 30 years ago and they allow you to build pretty much everything, if you're willing to spend the time. As time passes they come out with more advanced blocks, like the roofs in Lego. And just like Lego came with the little Lego men, gears, axles and so on, Amazon introduced more and more advanced services on AWS. But the idea, it seems, has always been to allow the customer to build pretty much everything she wants. Microsoft on the other hand seems to have followed the PlayMobil path. The fun is in the playing part and not so much in the building part. So open the Azure box and unlike AWS, you can start playing from day one. And as time passes by, there are more and more lower level components available, so you can start playing new games by building new toys.
Neither approach is better than the other, but you should carefully look at where you are, what you can do and what you want in order to be able to select either AWS or Azure. And IMHO, if you're just selected to go with Azure, don't even think about also doing AWS. And the other way around, because you would be most likely dealt lemons and you won't be able to make lemonade out of them.

API Management

First of all, API Management is a concept. I'm taking it you understand what an API is and I won't go into it any further than necessary for understanding this post.
API Management is done by people and some of them are using tools and technologies we call API Managers. Just like an enterprise, it has Management, and Management is made up of Managers.

Second of all, API-first design is not a fluke and it's not a hype either. Instead it is calling doom and gloom over your IT organization, or quite the opposite when you really know what you're doing.

Third of all, there's nothing MicroServices about API's although you see both walking around hand-in-hand more often than not.

Let's start with number 2...

API-first design
With API-first design, what you do is, you think about the functionality or information you want to expose and design it such that you don't have a clue about who will need or want to use that functionality or information. What you need to do next is worry about this. Start worrying a lot, because if you don't have a clue about who will access your functionality or information, let's call it a service, you don't know their intent either. And you don't know how often they'll access your service. You don't know whether or not you can trust them either. Are they taking security as serious as you do? Are they complying with all regulations you need to comply with? etc. Worries, worries, worries.

By not making any assumptions about the consumer of your service, you will need to make sure that it can stand the assault of all kinds of consumers. I do see your mind fluttering into the direction of non-functionals. Things like resilience and availability maybe? And encryption and access management possibly as well. Drop the mother in the cloud and you've got your scalability straight out of the Cloud's elasticity. (Of course you're very intimate with my post on this topic). And when you're in the Cloud, you know pretty much for sure that your Cloud provider will have all kinds of network protection in place without you even knowing it. Making sure that you, nor any other customer of theirs, will suffer from a DDOS attack and the likes.
But when we talk about API-first, we also need to think about the granularity of the service's exposed functionality or information. We need to think about it very, very carefully. In general we can say that less is more when it comes to this. But in fact, you want to hit that sweet-spot, because only then you're API is build to last.

That sweet-spot is something really important and almost impossible to find, let alone to hit. It's like the mythical G-spot. We know it should be there, but once you find it, you don't have the guarantee you will be able to find it all the times you're looking for it.
Granularity of your service defines it's usability and it is extremely business-bound. So first of all, you will need to know exactly the business context of your API and, and this is important, understand the business context of your consumers. And you should, no you must, accept that you'll have this latter one wrong. The most unlikely consumer will be your most valuable customer, so unless you're capable of reacting to her needs very quickly. Able to adapt to a massive change in positioning of your API in the grand scheme of the universe due to a pivot of your business, don't even try to go for API-first design.

By getting down to business, understand that an API is to be considered a product. It's not just access to your productised software solution, no it is your product. Nobody will care and shouldn't care how you do the magic behind the API as long as you're doing it. So you need to treat your API as a product. And that means that your API should have business value and as such, you should be very much aware that your API is valuable to your customers. In short, think about your revenue generated by your API. This is where your business context is showing it's ugly face again, because initially you can only assume how your API can be valuable to your customers. Hence you can only guess, albeit an educated guess, how you can get revenue from your API. Here again you'll need to be able to adapt to changing views and accept that hindsight is 20-20.
What this means is that you'll have to build (business) metrics into your API. Think upfront how you can verify your hypothesis and then do the validation of it as well. And don't be shy to change your product. A good product is one that is used, a great product is one that is valuable.
A key aspect of your API's granularity is about how elementary it is. You don't want to have an API that is only providing basic information, one that is only spewing data. Instead you want an API that is providing information in context. How much context is part of finding that sweet-spot. For example an Address by itself might mean nothing unless you know whose address it is, so a service that spews out addresses is of limited value, but one that provides access to a person and her address might be invaluable. Or maybe access to information is not that much of a thing to consider and instead you provide access to a function, for example to put some random text on API Management on the internet.

A good product is one that is used, a great product is one that is valuable.

The point here is that there's no way to determine what makes sense as an API and what not, unless you understand the context of your API at your end. And this only because it provides you with a starting point to make educated guess about the context of your API's consumer.
And at all times, the quality of your product needs to be such that you won't need to enter dialogue with the customer about the product, explaining why it's not working.

By the way, your architecture, blue-prints or design-patterns are no indication of what should be an API in the sense of API-first. In fact, I would argue that they are not an indication of what should be API's and managed as such and what not.
Considering you're developing according to service oriented concepts, and quite possibly adopting the principles of Forrester's 4-tier architecture. Which is in fact not a bad thing at all and probably a very beneficial view on things in general. So considering this, you might be inclined to consider very service in a specific architectural layer to be an API. For example the Aggregation Tier in Forrester's model or the Systems Tier in that model, could be considered to be an API. Which is total rubbish!
In software engineering we don't just do, we think about it and decide. So calling something a service in a specific part of our architecture an API is nonsense, should be cause of being fired in fact. And in fact, after thinking about it and deciding you have a service that is bound to be reused doesn't mean that will be an API either. So you'll have to do some more thinking... think... think... think. And then worry about calling something an API when you know in what situation the service is going to be used. Worry about calling something an API when you know who's going to call you to yell at you because the service is not abiding the service contract. Because if you know this, you know who your service's consumer is, and most likely there's no need to do any API'afyication on your service. Doesn't mean that you shouldn't treat it as an API, it means you don't have to treat it as an API if that doesn't warrant the effort.

In software engineering we don't just do, we think about it and decide.

API's have all kinds of stuff in them one way or the other, that allows them to be unleashed into the world. It's all the stuff that ensures that they survive the onslaught of calls by initially unknown subjects, the unsubs.
It's the part of API-first design that ensures that none of the wonderful promises of pots with gold by exposing the service's splendour, is compromised. It's the resilience, availability, scalability, security as well as metrics and other business requirements we too often consider IT stuff.
Think about the idea of implementing it over and over again for every service interface. If that means you're starting to sigh, and very deep at that, than only do it for the real API's. The service interfaces for which you don't know who'll call them. But when you get a smile on your face, eyes start to gleam, then you might as well take it from the other end; think about why you shouldn't treat the service as an API. Could be because of money (using standard tooling to API'afying service interfaces cost money) or maybe the operational overhead is not worth it.

So, in order to do API-first design, you need to understand your own business, meaning you need to understand what you want to expose and how you can create business value with your information or capabilities. This is hard enough for most software engineers, so they'll need the support of a business expert. Than you need to think about why others, and you don't know who that might be, would like to use your API, your product, and why it's valuable for them. This requires business knowledge and some understanding of how to see business value in using information flows. This is not the average business person you need to work with.
Than you need a thorough understanding of how to develop a resilient, performant and secure piece of software that can run in the Cloud, i.e. and elastic environment that is to be considered to be crashing all the time. And if you have all this in place, you need to be able to be roll-out new versions of your product on a very regular basis, with an extremely high level of quality. And on top of that, never get frustrated because your business pivots over and over again, because they're not really sure for whom the product is intended.

API's are about the hardest thing to create in software engineering. Designing software to act as an API before anything else is even harder.

Thanks once again for reading my blog. Please don't be reluctant to Tweet about it, put a link on Facebook or recommend this blog to your network on LinkedIn. Heck, send the link to my blog to all your Whatsapp friends and everybody in your contactlist.
But if you really want to show your appreciation, drop a comment with your opinion on the topic, your experiences or anything else that is relevant.


No comments:

Post a Comment

Note: Only a member of this blog may post a comment.