The importance of API Design

The design and construction of a building is a good analogy to exemplify the importance of API Design. A functional building that meets the residents’ and visitors’ needs with excellence usually starts with a good architectural design, then a good plan, engineering calculations and finally a constructor to do the job.

The world of APIs is not different: a well-designed API will generate numerous benefits, including an API with good usability, resilience and even good profitability.

Many API projects in the recent years have focused on mobility building Apps, and integrating with internal systems. Commonly in engineers and developers hands, these projects were born in the bottom-up model, meaning the definition of the API emerged during the development of the API itself. This situation eventually creates APIs with low-usability that can achieve internal integration needs, but can negatively impact Business-to-Business (B2B) and open API platforms as we will see later.

But why should we design an API?

B2B APIs and poorly designed open APIs impacts the business negatively.

In another analogy, I like to say that a B2B API, for example, is like a cable guy who will perform a service in our home. Our expectation is that the cable guy arrives on time, and performs the promised work quickly and efficiently. Other features such as kindness and cleanliness will add even more value to the service provided.

A B2B API is the same, and the API design assures that everything that can be done for the API-consuming user experience has been strategically studied and implemented.

Now imagine the open APIs, also called Experience APIs. These APIs will be consumed by third-parties who have no direct relationship with your company, and if this third-party is not satisfied with the experience from your APIs, this user will quickly migrate to a competitor affecting your business revenue.

To better exemplify the types of APIs and the importance of API design on them, I will reference the Axway whitepaper “Banking APIs: State of the Market Report.” This whitepaper presents the types of APIs and their influence on the business.

The image has three types of APIs and their importance to the business that we can exemplify as follows:

• At the top you have the Experience APIs which are the open APIs present in initiatives such as Open Banking and business platforms, and it is exactly these APIs that are most sensitive to bad API designs. In this case if the API does not deliver what it promises you will probably have a customer churn.
• Process APIs are Business-to-Business (B2B) APIs that focus on partnering with other companies. In this case bad APIs may be accepted by the business partnership prerogative, but may affect the profitability and success of the partnership.
• Core APIs are between the company’s core infrastructure and core active services, typically internal services that have not passed through a design process, but limitations on the importance of API design are circumvented internally.

APIs that are not previously designed and specified will cause functional problems and business difficulties. But what happens when your API is not well designed:

• Poorly documented and a complex documentation will delay the establishment of partnerships and business.
• Too many interactions to get or post data will create complexity and bad user experience
• Too many interactions to search and filter data will create complexity and bad user experience
• Authentication and authorization too simple or too complex for the digital channel will delay the establishment of partnerships and businesses, or may expose customers and partners to security breaches.
• API specification not responding accordingly to the developed back-end will create a bad experience and delay projects.
• Too many out-of-context functions or misalignment with the business motivation will create a bad experience and delay projects.

These are some examples of problems that occur when API design is not good, and all examples impact the success of the API and the business.

No specification or poor specification can make a project fail after consuming several hours and resources. Without API designing a wrong decision can be taken during the API building process, and it is not uncommon to find projects where the front-end cannot perform its functions because the API can´t do what it should do.

APIs are specified with market specifications.

Today the OAS specification “Open API Specification” is the most widely used.

We specify APIs with industry specifications that have been defined and are being updated and improved by experts. OAS is an example of specifying REST APIs with a series of native definitions and extensions to design an API with all the necessary features. There are other specifications but these will not be covered by this article.

The OAS specification uses a JSON or YAML format notation to define various API features such as: name, base URL, documentation description, methods and paths, request schemes, response schemes, request examples, response examples, contact, and other features.

In addition to the specification, we will need other support tools:

• Design Tool: A tool that helps us to easily design APIs, including functionalities to help the user without expertise or knowledge about the specification. One example is the Stoplight.io solution, which provides a visual studio for creating, generating, testing, and managing versions of the created specifications. In the image below the Stoplight Design studio.

• After create a specification we will need an API Portal or a Documentation Portal that is accessible to the developer, and it makes the developer life easier to learn and quickly use the specification to access an API. In the image below Axway API Portal with a list of APIs specified and available to the developer.

• And lastly, as a function of the Design tool or as part of the API Portal, a sandbox with API mockup examples created from the OAS specification. A Mockup API is designed to respond similarly or almost similar to the real API. It is a very useful feature for developers to understand the specification when designing the API, and also for developers to understand how to use the API before using it in production. In the image below the Axway API Builder component with the option to generate mock ups from the API OAS specification.

We can conclude that API Design is an essential first step to create successful APIs. In a world of Open APIs and open platforms, well-designed APIs will be vital to good business. We should combine dedicated teams to design business-friendly APIs, along with tools that accelerate and facilitate the importance of API Design.