There are many kinds and types of application programming interfaces (APIs). This book will only concentrate on a short list of them and this chapter is meant to get everyone on the same page.
What Is Understood as an API
An interface is a well-defined entry point into a system.
An electrical socket: There is a socket and a plug. The plug goes into the socket, and the device connected to the socket works.
A vending machine: You put money into the machine, you select the desired item, and the machine issues the item.
A helicopter: You pull the pitch and the helicopter takes off. You push the stick into any direction and the helicopter follows it.
These examples have one thing in common: they expose very complex systems in a relatively simple and easy-to-use form. Using a plug with a socket is extremely easy. Very little knowledge is required to use it. However, this is only true because the complexity behind it is hidden. You do not need to know where the electricity comes from and you do not need to know how the electricity is delivered to this one specific socket. You just need to match the style of plug and socket, and off you go.
The story around the helicopter is a little different. Most of you have not flown a helicopter but can still imagine that it is not a simple task. (I can assure you, it is not! I flew a Westland Sea King Mk 41 in a simulator during my time in the military and crashed it even after a successful landing!) The nearest machine to a helicopter that most people have controlled is most likely a drone. They behave similarly to helicopters but can often be steered using a mobile phone or tablet. It is difficult to imagine a simpler way of controlling a flying vehicle than that.
A fool with a tool is still a fool!
Full credit for that goes to my former colleague Niels, who brought that saying from San Francisco back to Switzerland. The message is simple: tools and interfaces only help skilled users!
Simple-to-use devices and applications ... and your own
If you have designed APIs for one of the first two UIs,1 I apologize, and you may stop reading now. If you are an expert on the APIs behind the third UI, I welcome you to continue reading.
Many developers believe a simple user interface is the result of great web design. Please note: they are most likely wrong. Simple user interfaces have very strong APIs behind them. Here is an example: when I attended my favorite workshop, IIW2 in Mountain View, California, Google gave a presentation on the topic of user authentication. To summarize it, the very simple login screen is powered by a system of 30 or more individual components and their APIs! These APIs are fed by the content of the search field and hidden values in the browser that are not visible to users and do not need manual input. Users do not even need to know that they exist!
Designing simple user interfaces is not an easy task. Developers of different areas with different expertise have to come together to make it happen. However, we will ignore UI-related tasks behind the user interface since this book is concentrating on server-side APIs. To get closer to explaining what is understood as an API, I will reference the user interfaces shown in Figure 1-1.
The example shows a user interface on the right side with many input fields, check boxes, and radio buttons—practically all UI elements are used. All of those elements are required because the UI is nothing more than a collector of data, which is required by an existing server API. Ending up with such a user interface could have several reasons: the server API needs the data to create an account, but no user context was available so nothing could have been prefilled or preselected. Developers felt it was the fasted and easiest way for them to implement it. Product owners could mistakenly believe that users need their system and therefore do not have a choice anyways.
Whatever happens, try to put yourself into the user’s shoes. Always consult UX experts who may be able to help with revisiting the design of your server APIs. You could support default values, you could implement server APIs that do not need all data at once, and you could implement a multistep flow that eases the use of your system.
In comparison, the simple user interfaces were built on top of well-designed and architected API systems. A possible approach to get there may have been a UI-first approach: design the UI and then design the APIs to support it! Similar, but not completely the same: the aircraft Fairchild Republic A-10 Thunderbolt II was designed around a tank cracking gun. Also, electric-first cars are designed around electric drive systems. In general, design what is important first but do not try to squeeze the square peg into a round hole!
- 1.
User clicks the “Display Catalog” button.
- 2.
The mobile app executes the client-side API named getCatalog().
- 3.
getCatalog() calls the external server-side API named https://server.external.com/mobile/catalog .
- 4.
That API calls the internal server API named https://server.internal.com/catalog?type=mobile .
- 5.
That API selects data from a database and transforms it into a mobile app-friendly response.
Client-side vs. server-side APIs
As my former manager Jay would say, Let me explain:
Box 1: The Client
A product owner wants a mobile app that displays a catalog. An app developer implements the screen to be shown. A client-side API developer provides a library (<script> .... </ script>) with an API (function) , getCatalog(). This enables the app developer to create a sexy UI and the one and only thing he has to do is execute getCatalog() that spits out exactly what he needs. The app developer does not need to know what happens behind the scenes, which simplifies his life as a developer. He can concentrate on building delightful screens.
Box 2: The External Server
That server exposes two external server-side APIs: /mobile/catalog and /web/catalog. These two APIs receive requests from mobile (as in this example) or web clients. The main task is to validate and forward these requests to the internal catalog API. As you can see, there is only one internal server side API, /catalog. It will be called with a query parameter (?type=mobile) to give a hint of the expected type of response. It may not be obvious, but these two APIs also help simplifying the mobile app/client API developer’s lives. Sending the query parameter ?type=mobile is not required for them. This is handled in the API /mobile/catalog.
Box 3: The Internal Server
The internal server exposes the internal server-side API , /catalog, which does all the work: it finds data from the database and creates a response matching the expectations of the client (either mobile or web).
A client-side API hides the complexity that is involved in managing requests to servers. SDKs3 are good examples of such API providers. A client-side API named registerApp() may register an application on a server. The registerApp() API (function) provided by an SDK may execute complicated tasks such as generating a CSR, extracting device details, managing user sessions, and sending and receiving requests and responses from servers. One single client-side API will often interact with one or multiple server-side APIs.
A server-side API exposes a well-defined entry point into and out of a closed system. There may be multiple APIs for the same purpose but for different types of clients. An API named /register may require five input parameters for clients that can provide application details, user details, and device details. The API /register/client may accept three parameters only if no user context is available. The latter API could add default values to compensate the missing user context but use the same registration backend as the first API.
I hope the difference between client-side and server-side APIs is now tangible.
An API is an enabler for business opportunities.
An API indicates how much users are appreciated.
An API indicates how much developers are engaged.
Nothing more, nothing less!
What Types of APIs Exist?
After reading this section you may be surprised to find types of APIs that you are aware off but have not been mentioned. Do not be surprised, please. This book is based on my own experiences and therefore any list cannot be considered as complete. It may also happen that you do not even agree on what I consider to be a type of API. In the end, I still hope that you get something to take with you.
From my point of view, an API has nothing to do with technology, at least not on a higher level. I once worked for a company that developed catalog creation/printing software. Their product was based on C++ but over time it also included Java. At some point, the CTO required every API to be available in both languages so that a developer could use her preferred programming language during product development. You could argue one API was of type C++, the other of type Java. I would argue it had nothing to do with type. No matter if it was used with C++ or Java, the usage was the same and the input and output was the same; it was just made for specific programming languages.
Finance: Banks, credit cards, debt collectors, financial services
Health: Doctors, hospitals
Insurance: Car, tenant, life
Gaming: Online gaming
Government: Public services
Shopping: Including mobile services, electronics, tools, foods
Logistics: Managing goods transportation in general
I like the categorization by use case since almost all companies can assign themselves to at least one of them. The advantage is that regulations, best practices, specifications, RFCs,4 or laws are in place that should or have to be respected. Being able to approach types of APIs this way takes you half way to your requirements document without reinventing the wheel.
PCI: Payment Card Industry security standards. If your system handles any credit card-based transactions, you must be PCI-compliant.
FIPS 140: Federal Information Processing Standard, publication 1 and 2 (FIPS 140-1, FIPS 140-2). Issued by NIST5. Applies if cryptography is required, which is the case for financial institutions.
PSD2: Payment Service Directive 2. A European directive to force financial institutions to create APIs for accessing account information (high level). This is required for European institutions but should also be considered outside of Europe.
FAPI: Financial-grade APIs by OpenID Foundation. A list of typical requirements to support financial tasks such as checking account information and transferring funds between accounts via APIs. Meant as a guideline for any company that has to adhere to PSD2.
While talking about types of APIs, I would like to remind you that you should never categorize them by their visibility such as “private” and “public.” What I mean by that is the concept of calling an API private only because it is not publicly documented or publicly introduced otherwise. It has been shown that any kind of API will be found by someone and then misused. Even if you are exposing APIs for private consumption, you should always treat them as if they had been made publicly available! Assuming you are safe since your API is private may lower your standards in regards to authentication and authorization, rate limiting, and sanitizing content that gets exposed.
After reading about a “breach” of your very own system in the press, you will find yourself in your company’s head office having a chat with your CEO—the type of chat you may have had during school time with your principal when he was not amused with you!
B2C: Business-to-consumer
B2B: Business-to-business
Type B2C: Leverage an OAuth (RFC 6749) and OpenID Connect ( http://openid.net/connect ) infrastructure. These protocols cover authentication, authorization, and resource API protection. Guidelines for mobile app development (RFC 8252) exist. OpenID Certified providers (cloud and on-premises) already exist and can be considered ( http://openid.net/certification/ ). You can calculate the concurrent sessions you need to handle and with that you can lay out the required infrastructure.
Type B2B : Leverage an OAuth and OpenID Connect infrastructure or use SAML for federated user authentication and authorization. SAML ( https://en.wikipedia.org/wiki/SAML/_2.0 ) is well supported.
Support: Your support team needs to be available 24/7. That team needs to have at least one expert per system component. You may even need to include engineers to be available on-demand.
Redundancy : Your system needs to have redundant system components. And it is important to pay attention to details. Here is an example: if your system requires a web server, you need two of them. If any web application running on that server needs a database, you need two of them, too! It may sound obvious, but I have seen it all.
CI/CD: You need to have a CI/CD chain that allows you to update your system at any given time. The CI/CD chain needs to be automated, not scripted! Especially with redundant components updates cannot be applied manually. Otherwise, sooner or later, your components will run different versions of the same software and escalations will be unavoidable.
Summary
It is important for every project to clearly understand which type of API needs to be supported. Knowing this guides the project in the correct direction. Many requirements can be derived from that information. After reading this chapter, all involved persons should be on the same page or at least know which questions to ask before going ahead.