Matthias Biehl - API Architecture: The Big Picture for Building APIs

API University Series - Volume 2
www.api-university.com

Copyright 2015 by Matthias Biehl
All rights reserved, including the right to reproduce
this book or portions thereof in any form whatsoever.
ISBN-13: 978-1508676645
ISBN-10: 150867664X

Looking for the big picture of building APIs? This book is for you!

Building APIs that consumers love should certainly be the goal of any API initiative. However, it is easier said than done. It requires getting the architecture for your APIs right. This book equips you with both foundations and best practices for API architecture. This book presents best practices for putting an infrastructure in place that enables efficient development of APIs.

This book is for you if you want to understand the big picture of API design and development, you want to define an API architecture, establish a platform for APIs or simply want to build APIs your consumers love.

This book is NOT for you, if you are looking for a step-by step guide for building APIs, focusing on every detail of the correct application of REST principles. In this case I recommend the book API Design of the API-University Series.

What is API architecture? Architecture spans the bigger picture of APIs and can be seen from several perspectives:

• API architecture may refer to the architecture of the complete solution consisting not only of the API itself, but also of an API client such as a mobile app and several other components. API solution architecture explains the components and their relations within the software solution.
  
• API architecture may refer to the technical architecture of the API platform. When building, running and exposing not only one, but several APIs, it becomes clear that certain building blocks of the API, runtime functionality and management functionality for the API need to be used over and over again. An API platform provides an infrastructure for developing, running and managing APIs.
  
• API architecture may refer to the architecture of the API portfolio. The API portfolio contains all APIs of the enterprise and needs to be managed like its product. API portfolio architecture analyzes the functionality of the API and organizes, manages and reuses the APIs.
  
• API architecture may refer to the design decisions for a particular API proxy. To document the design decisions, API description languages are used. We explain the use of API description languages on many examples.
  

This book covers all of the above perspectives on API architecture. However, to become useful, the architecture needs to be put into practice. This is why this book covers an API methodology for design and development. An API methodology provides practical guidelines for putting API architecture into practice. It explains how to develop an API architecture into an API that consumers love.

A lot of the information on APIs is available on the web. Most of it is published by vendors of API products. I am always a bit suspicious of technical information pushed by product vendors. This book is different. In this book, a product-independent view on API architecture is presented.

The API-University Series is a modular series of books on API-related topics. Each book focuses on a particular API topic, so you can select the topics within APIs, which are relevant for you.

People use software via a user interface. Applications can use software as well, via an API, an Application Programming Interface. Thus, an API offers a simple way for connecting to, integrating with and extending a software system.

APIs are a generic concept that can be used in many ways and thus there are many definitions that capture one aspect of APIs, such as:

• An API is a web service: It delivers resources via web technologies such as HTTP. APIs are used for building distributed software systems and enable loose coupling.
• An API is simple, clean, clear and approachable: It is like a socket that different apps can connect to easily, just like different appliances are plugged into an electricity socket.
• An API provides a bridge between company-internal data providers and company-external data consumers.

APIs are usually not visible on the surface, do not offer a user interface, and typically no end user will directly interact with them. Instead, APIs operate under the hood and are only directly called by other software. APIs are used in machine to machine communication and the integration of two or more software systems. The only people interacting with APIs directly are the developers creating applications or solutions with the APIs.

This is why APIs need to be built with the developers in mind who will integrate them into new applications. This means that the ease of use for the developer is extremely important. APIs need to be simple and efficient from their perspective. This often requires a change in the perspective for building services. So far, services have been built form the perspective of the service provider. APIs need to be built from the consumer's perspective.

An API offers a simple way for connecting to, integrating with and extending software systems. Now, think about the entities that are run by software. Businesses, markets and banks are run by software. Industrial production processes are controlled by software. Machines, cars and many consumer products contain software. However, these software systems are typically isolated and functionality of one system cannot be accessed from the other system. APIs provide a possibility to connect these separate software entities. APIs provide the capabilities which are essential for connecting, extending and integrating software. And by connecting software, APIs connect businesses with other businesses, businesses with their products, services with products or products directly with other products.

Just one example for the business to business integration: The business of an enterprise can be expanded by linking the business to partners up and down the value chain. Since businesses are run by IT, the businesses can be better linked by integrating the IT systems of a business up and down the value chain to the IT systems of other businesses, partners, employees and to customers. A business can strive if it is better linked to its external partners. This can be accomplished if the IT systems of the business partners are linked via services.

However, an enterprise cannot force its business partners to use its services. It can make these services so good -- so valuable and simple -- that the business partners will want to use them. If these services are good, they can become a means for retaining existing partners and a means for obtaining new partners. But what makes a service good? A service is good if

• it is valuable and helps the partner to perform his business.
• it fits the exact needs of the partner.
• it is simple to understand.
• it is easy to integrate and monitor for the partner.
• it is secure, reliable and performant.

The infrastructure for enabling this connection is already in place. Each and every person, each employee and each customer has a smart, internet-enabled device, businesses have websites and web-services. Even an increasing number of the products sold by the businesses carry digital sensors and are internet enabled. All these devices are connected to the internet and can - in principle - be connected.

APIs are used for internal and external integration. APIs can enable better integration between departments and business units of a company. Amazon, for example, uses APIs to integrate the IT systems of its departments. If the interfaces and technology are already in place for internal integration, it becomes easier to provide external integration. External integration is used with business partners or external entities for staying competitive. External APIs are also necessary for realizing mobile apps. Interesting mobile apps use company data, data that is delivered to the app via APIs.