Why should I care?
Some have asked me if anyone else than technical people should understand APIs at all? Short answer is yes. Longer answer around the blog series. APIs should not be seen as technical - but as constructs.
API development driver should be the business. Thus business development staff at your company should be well-aware of the opportunities APIs bring to grow your business and in some cases reduce cost structure. Your IT architects should see the benefits of APIs; flexible, agile and scalable architecture.
But now the discussion has turned already away from technical nuances of APIs towards the value APIs can and should provide for Consumers. In this context consumer refers to application developers, who are seen as the primary customer, not the end-users using implemented applications.
Create API prone culture
Before jumping into developing own APIs, you should make sure your company has the capabilities and will to utilize APIs. It is more likely that you will end up utilizing more APIs than publishing own. Thus it is important to build API culture inside your company first. You don’t have to be as dramatic as Jeff Bezos was (API Mandate), but you have to build API prone culture inside your organisation, because you probably start building own APIs for internal use only. Your first API customers are your own staff. That’s how Amazon and plethora of other companies have started API journey.
APIs are standard lego blocks of practically any digital service. Services are constructed by utilizing own APIs or APIs provided by other organisations. Good API solves a problem. Everyone knows API should be easy to use, but API should be hard to make mistakes as well. It might offer login and user management, map based routing, convert currencies, check URL vulnerability, handle payment process, to mention a few. APIs make it easier and faster to develop new services for masses.
I’ve read about 200 articles and books about APIs while trying to create solid fact based classification of APIs. Based on literature APIs can be divided to three major categories: Open Data Interfaces, Open APIs, Internal and Private APIs. The classification was initially created for the API Economy book published 2018 in Finnish and 2019 in English (Moilanen et al., API Economy 101)). Below API cheatsheet is reproduced from the book.
Let’s have a look at the API types in details.
Open data interface
Is often provided by public sector organisations. Their interest is on that data is(should be?) used as much as possible. Thus they charge minimum for the usage (or then it might be free) and use open data license (often Creative Commons) in content provided. In the previous examples about my morning routines, I talked about a location tracking app for buses across Tampere city. That app (and many similar) is fueled by open data interface, provided for free by city of Tampere, which offers location of all busses every second.
First subsection of Open APIs is Public API. This is what most often people refer to when discussion turns to API economy. Public APIs are available for all to consume. These APIs are listed in ProgrammableWeb and similar API catalogues. They might have cost structure and often part of it is free-tier. Free-tier provides API usage for free under some conditions set by the API owner.
Sometimes architects and internal API development teams forget for whom the public APIs are created. APIs are said to be published for others to consume but too often public APIs reflect the internal architecture of the system. The API consumers don’t give a crap about your internal architecture. They want to get things done as easily as possible.
Let’s take an example. There is a special API category, called Data Broker API which provides data from various sources and data source is given as product code attribute. The needed attribute is found out by calling another API (categorized as Product API). The API consumer might start from Data Broker API documentation and find out that to get needed data, s/he needs to call different API first to get the product code. Consumer needs to authenticate to two different APIs too and learn two data models. Reason to this might be that, in internal architecture different microservice components handle the data streams and marketplace product management. The situation gets even worse if you use serverless functions as APIs. Would you then document each function as API? Or would you rather group the functions based on consumers needs?
As an alternative design approach, the endpoints could reside inside the same API, for example Product API. This way consumer learns to use one API and probably the endpoints are described side by side in one documentation. Which is easier for the API consumer?
Thus exposed APIs should be organized and build to fit API consumer's needs and processes, not to reflect your internal architecture.
Second subsection of Open APIs is Partner APIs, which are the most lucrative API species at the moment. Partner APIs are not available publicly for anyone to consume, but opened for dedicated partners after thorough business opportunity evaluations. Until lately, all partner-APIs have been under the radar e.g. not visible anywhere, not even in the company or product website. Gradually that has changed and information about Partner-APIs are surfacing and in even some cases, the documentation is available.
Internal and private APIs
Internal and private APIs are hidden gems. This is from where companies begin their API economy journey. While building internal APIs, company learns how to build and maintain APIs. The created APIs are used internally to automate processes and reduce costs in operations. The biggest mistake you can do with internal APIs, is not to treat it like it would never go public.
Internal APIs are the key structure of your IT architecture since connecting systems to each other is built with APIs. Not to document your internal APIs is like waiting for the Unabomber visit. It might not come, but when it comes, it will blow away half of your company. If the API developer is the only one who knows how API works, you are on the mercy of that developer and keeping him or her onboard is vital for you. Security is also one of the most neglected aspect of internal APIs.
Good practise is to treat internal APIs just like they would be published anytime soon.
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!