Roadmaps are why you should ditch your architects

Summary

Architects that are not with you along the way are of no use. You should not pay too much attention to them, they're not worth the frustration they cause as nothing good will come from it.
But if you find yourself in the company of an architect that is trying to be with you all the way, you should cherish that architect and consider yourself extremely lucky. Not only because your life will be better, but more importantly because this is a very rare breed.

Classification of Architecture Irritation

In case you're interested in finally getting that excuse to get rid of your architects, you're most likely frustrated with them, their architecture and probably you are not able to see any added value of the architect in your organisation. Therefore, I think you'll most likely fit into one of these groups:

• Your architect is too technical and strict, and that the architecture is too restrictive and technical.
• Your architect is just the right person for the job, and a great job he's doing with that just right architecture.
• Your architect is too high-level and vague to be helpful, and that the architecture is too high-level and vague to be useful

And in case you are an architect, you will fit in one of these three categories and your surroundings classify you as either too strict, awesome or just not helpful at all.

Now think about it really carefully... if you're the just right architect or you're dealing with that architect. Since how long do you feel that way? Has it been forever? Well, then this post isn't for you, but continue reading anyway. In case your answer is something like 'just recently' or 'since not so long', then this post is for you because there's a reason why it's been not since forever and it's bound to change in the near future. Well, it'll be very likely you'll going to move to one of the other groups.

The roadmaps are what make architects roadkill

When your architect already is one of those that you can't really consider useful, and is creating architectures that are not really helping you. Or when you're one of those architects. Well, you're in for a treat, because this is a cause of possibly the main frustration within your IT department. Or even within your whole organisation.

Now why is this?

This is because these architects only add time and costs to your projects and nothing else. They too often behave like auditors, telling you what's wrong and not how to fix it. But other than auditors, the architects refer to something they created themselves in the past, using the RTFM reply.
Auditors are a pain in the buns because they point you at how you're not playing by your own rules. Based on what your own definitions of good and bad are and what is and what's not acceptable, they'll verify to what extent you play by those rules. Architects, too often, will work on a reference architecture, architecture principles or even guidelines and that's it. You use their output to work on your own products. And you'll notice that as soon as you start using their stuff, it's either too restrictive (we develop software in either Java or .Net), too outdated (we develop our software based on JavaEE 5) or too vague (we develop our software based on the multi-tier architecture). Whatever it is, it's not helping and as soon as you ask your architect to do a scan of your products, it will be noticed that you're not using Java or .Net but NodeJS instead, that it's based on Java 8 or that it's an architecture based on SOA principles utilising a serverless infrastructure using Amazon Lamda.
So by either abiding the rules written or checking to what extent your compliant, you're loosing time and wasting money.

In many cases this is because people think architecture is a noun, while it is in fact a verb. Let me repeat that;

Architecture is a verb, and definitely not a noun!

So when you document an architecture, you're documenting a living thing. Something that is changing constantly.  So understand that when you come across a document with an architecture, look at the date of the document, because it's a snapshot of what the architecture looked like at that date. Or rather, it's likely to be the case.

But it doesn't end there, architecture isn't just some thing that changes constantly. It's an opinion of somebody who is mandated to be opinionated. What this means is that the architecture is also showing where you want to go as an organisation with your IT landscape. It's the as-is, the to-be and the route to get there. It's like a sat-nav system, it determines based on GPS coordinates where you are on the map, you enter your destination and it will calculate the route to follow to get at your destination based on your location. This is architecture. Well, part of it. The part that's relevant for this post.

That reference to driving and navigation is something I've done before. Read about it here. It's how I explain to my kids what my job is. I see where my client is, I negotiate with him where he would like to be and then come up with a plan how to get there. Including a clear definition of the impact on his situation along the way. Goods and the bads of the trip.
When you look at how many architects work, it's no surprise that they're so frustrating. The analogy with the SatNav is very clear in this;
There're those that will just hand you a (road)map and you just figure it out. See where you are, find where you need to be, plan your trip and go. And oh, btw, the date on the map is likely not very comforting. Or you'll get a turn-by-turn overview of how to get from A to B, based on the outset of when you started to plan your trip. It's based on some possibly old view of the world and any changes to the roads, terrain or otherwise are hopefully taken into consideration. But any traffic jams or other obstructions along the way are not in scope.
And then there's our trusty connected SatNav system. And the analogy holds. Because this thing is connected to the world. It not only keeps track of where you are during the trip itself, but it will keep an eye out to where you will be shortly. That won't be your final destination, but in case there's some roadwork up ahead, it will guide you past it. You'll be informed about relevant information along the way about gas stations and gas prices, hotels, restaurants etc.
The interesting part here is that those that have ever driven with a map, remember the fights between the driver and the person reading the map. Or those near death experiences when you were driving and reading the map yourself. And in case you printed that yahoo page with the turn-by-turn route to wherever you thought you were going to end up, you'll remember that all of a sudden there's a lot of places with the same name, roads are always under construction and the turn-by-turns are always irrelevant after the 5th turn or so.
These are the architects that think architecture is a noun.

The SatNav is constantly with you, and the better the system the more it anticipates on the road ahead, keeping you informed about your surroundings, distance to destination as well as the arrival time. It will keep in mind that weather conditions might be cause to divert your trip or maybe start the AC to make sure that the climate in the car matches the weather outside. This is when architecture is a verb.

Architects that are not with you along the way are of no use. You should not pay too much attention to them, they're not worth the frustration they cause as nothing good will come from it.
But if you find yourself in the company of an architect that is trying to be with you all the way, you should cherish that architect and consider yourself extremely lucky. Not only because your life will be better, but more importantly because this is a very rare breed.

Conclusion

I did already post about project managers and their demise here. Well, it's not a lot better when it comes to architects. Actually it's worse, because these architects, the ditch-able ones, are useless even in waterfall projects, but more so in agile projects, I give you that.
But where you can still find some use for most of the architects in waterfall projects, because as you know, these projects consider documentation as a key deliverable and are run under the premise that after creating the documentation for the next 12 to 24 months they don't need to change. In Agile projects this is different and this is why many scrum teams have said their goodby's to architects and even organisations have stated that architects are no longer need. And yes, this is the best thing that could have happened to our profession as IT architects. It's a matter of weeding out the turn-by-turn style and map style architects.

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.

Iwan

API Management in Azure using Microsoft's solution - API's and Architecture, match made in heaven

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.

Summary

The architect is arguably the one most concerned with API's as it is determined by the architecture where the API's reside, what should be API'afied. This has nothing to do with application architecture or integration architecture. The architectural structure of software has no relevance as to when and what to expose through an API. It is the business or domain architect that decides what will be exposed through an API, when and only when the Product Owner wants to reap the benefits of an API to his product. API development may not be controlled by rules, instead it should be governed by principles and guidelines. Although why something should be exposed as an API is a business (architect) call, the how it is exposed is a technical (architect) call.

API's need empowered teams to develop them and more importantly to maintain them. This is not an small thing. API's being extremely hard to develop, they are also extremely strainuous to an organisation because they typically upset the whole structure of the organisation. Even when that organisation is already a product organisation with product teams and product owners.

API's and Architecture

API's are among the hardest things to develop. Why this is, you can read in my previous post here. I think that the role of the architect is extremely important when it comes to API's because they provide access to functionality and information without compromising the underlying systems. And it's not access to just some information, but to information that has meaning on a business level. It's about disclosing your business to the unknown consumer. Well, it's the consumer of your API. So this means that your API's need to fit into the grand scheme of all things IT in your organisation. This is where the architect comes in, because the architect is the city-planner of your IT landscape. See my post on the role of the architect in your organisation, and how that architect may fail miserably here. 

Basically it would be the architect that has a strong say in what the boundaries of your IT landscape are and therefore where the API's are to be found. Mind that this is the IT component of your business architecture.

Say what? Well, it's not that difficult to understand. Consider your business architecture, in a world where IT is considered in terms of products that the organisation is making money off. (As opposite to seeing IT as an enabler or unique selling point.) So basically the organisation defines its business in terms of products. These products and the relationships between them are a way to see the business architecture. It's a very complex exercise to do this and on top of that, many organisations don't even want to make money perse. GO's and NGO's are examples. Still, consider that you do stuff that is of benefit to others, than what you do and what you'll do it with are your products.

These products are at times realised using IT. Maybe the full product is IT or parts of it are. These IT products and their relationships are the IT components of the business architecture I was referring to.

Every connection between any two products is a prime candidate of becoming an API, or becoming API'afied, if that were a word.

Did you notice that I am referring to the business architecture of the organisation and not to an application architecture that is adopted by an organisation. For example, I'm not referring to the 4-tier architecture by Forrester, or the traditional 3-tier (presentation, business, data) architecture, or an SOA or anything like that. Like I discussed in the API-first design post, these architectures have no relationship to your decision what should and what should not be API's. Your business architecture is. Sometimes, especially in larger organisations, that business architecture is decomposed into multiple domain specific architectures, again on a business level. Here you might argue that the relations between domains are even more prime candidates to become API's. And again, how your application architecture is defined has no effect on that.

The Platform

So this is where the architect has value in the API driven universe. Consider this; API's thrive in a platform economy, who decides whether or not there will be a platform and how the platform is shaped? It's the architect and no one else. And this is because the architect is the only one that views things beyond product boundaries, that's the architect's scope. The Product Owner and his Product Team are only concerned with the product. A true Product Owner will also understand the value of API's, because it means more users of his product and more users means more value, but it's the architect that decides a platform is to be developed, raising the value of API's several levels upwards. You should take a look at 'The Age of the Platform' by Phil Simon to understand the value of a platform and why it is such a key to success for many fast growing organisations. Mind that platforms are not only valuable in relation to external customers but also for internal customers.

So basically, the architect is the key role when it comes to API's. The architect defines the business architectures, models the IT products in it, considers where interfacing between domains and products is done through API's. The architect also decides whether or not to work on a platform and that kind of implies going for API's as well.

Organisational Impact

It should also be the architect to determine whether or not the organisation is fit for developing API's. Like I stated in API-first design, developing API's is one of the hardest things to do in software development. Which not only implies, but makes it rather explicit that your organisation needs to be ready in various areas to be able to develop and maintain API's. Continuous Delivery, and preferably Continuous Deployment needs to be in place. You would like to strive for a DevOps IT organisation and you need a very capable Product Owner. On top of that the developers working on API's need to be able to understand the relevant business concepts and need to have extensive experience in the pitfalls of software development. The architect's responsibility is to inform management, including HR management, the impact of adopting a platform strategy, or an API strategy on the organisation. Since architects need to be able to quantify the impact of a change to the IT landscape across all aspects of the enterprise, the architect will need to be able to quantify the impact on staff, staffing and processes alike.

Think about the opportunity to start small, have a single team mature enough to develop and maintain API's. That team should be mandated and thus empowered to develop API's and put them in production, with full autonomy. If the team needs to deploy in production, it should be their call. They should be held accountable and they're responsible for the success of the API. Once that works take all lessons learned and scale your organisation to more teams to work on API's for their products. The architect will know what domain and what product will be best to provide API's to interface with in order to create the most business value.

Governance vs. Control

And then there's the other thing, which is governance. There's no room for control in an API economy. A Product Team that develops API's to access the product's information and functionality will need to have full autonomy. And that means that it can't be controlled. Control means that there's a committee that decides whether or not the team has been abiding by the restrictive rules defined by some other committee. This assumes that it is possible to define rules that API's need to follow without knowing the API and therefore the context within the API is being used. Utterly impossible because when you start developing an API you have no clue about your customer and by monitoring very closely you get an understanding of who your users are and why they want to use your API.

So should there be no control at all? Of course there needs to be control, but it's of the scalable kind. Scalable control is called governance. Governance is done by first define a series of principles. A principle is a rule or belief that governs ones personal behaviour. It's intention is that because one believes that the principle makes sense and one is better off by applying the principle, life is better.

A principle is a rule or belief that governs ones personal behaviour.

By their very nature, principles are used for governance and not for control. It's is one of the most formidable ways to get self organising and autonomous teams work in concert and by the same playbook. The interesting part here is also that you can choose not to stick with a principle in a certain situation. A clear motivation is available implicitly because one abides by the principles, unless there's a good reason. It also allows in your governance structure room for classifying principles in those that can be dropped when the team chooses so and which need an explicit approval from some authoritative body, like an Architecture Board.

Besides the principles, which are set by the architect, the architect needs to define a set of guidelines that inform the Product Team the best course of action to develop an API. These can be related to processes, like how to publish an API. But also technical, for example naming conventions, versioning strategies, etc. Good guidelines are no-brainers but converge various alternative solutions to a problem into a single solution that is the default selectable solution to the problem. It's different from a principle because it's not appealing to a developer's common belief system but to the developer's common sense.

Governance is an architect's dominion. It's not related to a specific team, but it's there to ensure the integrity of the complete IT landscape. This is where the architect shines. The Product Team is responsible for its own principles and guidelines and they should never conflict with the overall, architect driven principles and guidelines. One could argue that the team only makes architecture decisions, based on the principles and guidelines.

Mind that principles are hard to define, almost as hard as API's. Always think of an API as something that sounds like a rule, that has a clear rationale and has an impact which on the one hand details the impact on the existing landscape, the external impact. But also has an internal impact, which details limitations, prerequisites etc on how the software subjected to the principle is developed.

Quite often I see principles that hint towards solutions. For example: High available systems are deployed on a cluster. The rationale is clearly a technical one and the impact restricts the technical aspects of the solution. But an architecture principle's rationale should be a business rationale instead. The impact should allow for as much freedom to the team developing the software without compromising the principle. For API's one needs to be extra careful when defining principles. Stating that API's are always exposed as SOAP webservices seems to be a good principle. SOAP is a great way to do b-2-b integration and it allows for a standardised approach to security, validation, etc. But what if the better way to expose the API is as a RESTful service using JSON? Well in that case the Product Team can motivate why the principle is dropped. But a principle like API's are always exposed based on internet standards and web-based protocols achieves the same, it also allows the product team to select the best solution for their situation and still hold on to the principle. Furthermore, the architect could define a guideline, or guiding principle, stating that for b-2-b connections SOAP is preferred and for b-2-c REST/JSON is preferred.

Empowerment

I've stated before, the Product Team should have a high degree of autonomy when it comes to API development. You want governance in place to make sure that anarchy won't reign. This means that the Product Team should be empowered to decide for itself when principles are selling them short, when a new not yet anticipated situation surfaces or the API's 'market' changes over night due to new insights. In addition, you want the team to be empowered to decide how they develop API's in the most efficient way. Meaning that thinking of an API and having consumers calling the API should be an efficient as possible process. This is an important statement, because it means that the team can't just say 'screw the process or the organisation for that matter' because they have autonomy. Because doing so, would not benefit the complete process from idea to used product.

The complete series:

• API-first design
• API's and Architecture, match made in heaven 
• Why API's should be managed and by whom
• Resources and Templates [1/2] 
• Resources and Templates [2/2]

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.

Iwan

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.

Summary

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 Amazon.com 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.

The complete series:

• API-first design
• API's and Architecture, match made in heaven 
• Why API's should be managed and by whom
• Resources and Templates [1/2] 
• Resources and Templates [2/2]

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.

Iwan