People often ask why API enthusiasts keep recommending design by contract. After all, specifying the interface design with programming is much easier. The code includes everything that’s needed anyway, including content checks for correctness. Well, that isn’t easy to dismiss. The statement isn’t necessarily wrong. Generally, code is the single point of truth and is therefore responsible for correctly processing functional data.

However, as in real life, this is only one side of the coin. Design isn’t the only aspect that matters; there are other points to consider.

• Infrastructure: Before a resource can be accessed, security-related hurdles must be overcome in modern infrastructures, and rightly so. But these also increase a request’s latency since the path to the actual processing service is significantly lengthened.
• Zero trust: Security once again, but from the perspective that every component in a chain is responsible for security. Authorizations at the API method level also play a role.
• Vendor lock-in: This is exactly what must be avoided in order to replace the tooling if necessary.
• Validation: “Am I doing the right thing?” How can I tell if this is the case?

These are just a few aspects that need to be examined. They affect almost all levels of technical communication via HTTP APIs.

This is where standards come into play

We can already see this is a complex environment that can’t be understood in its entirety. To cope with this complexity, there are comprehensive standards designed to help us design APIs. We’ll primarily consider two types of standards:

OpenAPI – Standard for synchronous API communication

The OpenAPI Specification is a standard for describing HTTP application programming interfaces (APIs). It can also be used to define REST-compliant interfaces. The specification is promoted by the OpenAPI Initiative. The initiative’s vision is to provide an open and vendor-neutral description format for API services in the spirit of a connected world. The project is supported by the Linux Foundation.” (Wikipedia)

OAuth2/OpenID Connect – Standards for authentication and authorization

OAuth 2.0, which stands for “Open Authorization”, is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user. It replaced OAuth 1.0 in 2012 and is now the de facto industry standard for online authorization. OAuth 2.0 provides consented access and restricts actions of what the client app can perform on resources on behalf of the user, without ever sharing the user’s credentials. – (Auth0 by Okta).

OpenID Connect (OIDC) is an authentication layer based on the OAuth 2.0 authorization framework. The standard is a layer above the OAuth framework that allows clients to verify a user’s identity using an authentication server and obtain basic profile information in an interoperable manner. The implementation of OpenID Connect is based on the HTTP programming interface with REST mechanisms and the JSON data format. The standard is monitored by the OpenID Foundation.” – (Wikipedia)

There is actually a third standard for asynchronous communication called AsyncAPI. However, we will not discuss it here.

Someone may say, “That’s all well and good but standards can sometimes be annoying, cumbersome, and restrictive.” That can’t be denied, yes. Standards are usually the result of the process that aims to reconcile as many requirements as possible. But in return, they offer a whole host of advantages.

Independence from manufacturers, programming languages, etc.

This is at the top of the list. Recognized standards let you act agnostically from external influences.

For example, OAuth allows you to work with different identity providers (who’s ever logged into another application with their Google account?). This ensures a basic level of security, which the standard has already defined.

HTTP APIs are already highly independent per se. But for development, it’s important that OpenAPI sets certain syntactic (type safety) and semantic (correct date specifications) requirements that help enable language-independent communication. We’re supported by many tools (just one example: API Design Editor from Swagger) to formulate, validate, and ultimately bring APIs into production.

Structured solution options

Standards also help with development work. They allow patterns to be recognized and corresponding solution spaces to be built up. These are then filled with life in the actual development. This also applies to API design.

We’ve learned that there is no such thing as the API. But it can be very useful to respond to consumer concerns and, under certain circumstances, offer appropriate communication options. At first, this can sound daunting, especially in terms of development and maintenance.

But there are already design patterns in development to deal with these scenarios. These can also be applied in API design. This makes it possible to specify different APIs, but send them to the same backend with different data structures. This can be taken so far that it’s possible to formulate the access behavior for the consumer at runtime (HATEOAS).

Durability and interchangeability

These two issues are especially important for companies because time and time again, developments are viewed as long-term investments. Adam Bien once said, “Use standards that have been around for a long time”. And in a way, he’s right: there are always one or two nice implementations or solution ideas, but these approaches come and go. Standards survive, and that’s a good thing. Even if the infrastructure I’m using no longer exists, I can switch to another provider without needing to change the actual design. It stays transparent for consumers.

The situation is similar for producers. Although behaviors (e.g., deployments) and sometimes sequences change, the API itself stays the same and can be processed by the new provider—provided the provider supports the standard.

Focus can be placed on technical expertise

This is a brief recap, the question is: “How can I ensure that exchanging information doesn’t backfire on me as a provider?” It’s true that request content should be validated on the backend. But missing type specifications (such as length specifications) in the specification can place an excessive strain on resources in the network. This can go so far that systems fail. This isn’t only because technical details like the type, scope, and/or information format haven’t been described, but merely assigned character strings.

The exciting thing is that tools take these definitions into account. During conversation, generators also take them into account(e.g., into source code). It doesn’t matter whether this involves client or server generation.

API Management

To establish communication, we need infrastructure in the form of API management. What does API management offer? In short, it offers three components:

• API Manager: This is the development and management environment for APIs. The environment is designed for developers and supports them in API design, provision, and lifecycle management. In most cases, the environments can support multiple types of APIs (http, GraphQL, etc.). Actions can be defined in this environment to control the throughput of a request. Key words here are validations (is the API content correct), rate limiting (are the available capacities being overloaded?), and/or security (OAuth2: authenticity and identification).
• API Gateway: This artifact is the gateway to a provider’s processing environment and offers corresponding security measures. These vary in nature and are generally specified as policies (e.g., authentication). Therefore, there will be default policies from context to context that represent basic security. However, these can be extended to include policies that have been specified for specific situations (content validation, rate limits, etc.). Individual validations will be performed via the API specification.
• Developer Portal: This is the offer portal for consumers. It displays the entire range of services offered by a provider for machine communication. Here you will find the API’s scope, type, documentation, and usability (public or subscription-based). Many developer portals also offer corresponding playgrounds where you can get to know APIs and test them.

This is only a small excerpt of services API Managements offer. They also offer monitoring services, which we won’t discuss further here.

What are the benefits of these infrastructure environments? Above all, they save time, enable fast responses (fail fast), and provide security (see Policies). The configurations for each API are stored in the management system and are analyzed and validated according to the set criteria at a very early stage—immediately upon receipt of the request. This means requests can be blocked there because specified standards haven’t been met or because the validation was completed with a negative result.

Standards help us throughout the entire life cycle

Even though standards can sometimes seem annoying, they offer significantly more advantages than disadvantages. We can rely on extensive support, regardless of where we are in the chain. For API providers, the range of possibilities has increased significantly. Standards make it possible for tasks to be performed reliably at other locations in order to conserve their own runtime resources. As a consumer, I can trust the API has been described in detail in terms of scope and behavior and will reliably and correctly deliver the information I need.

Conclusion

Interface design isn’t really a new topic. IT simply doesn’t work without interfaces. But the introduction of APIs changed a lot. Ultimately, the reach of offering via the Internet has increased dramatically. Companies are also discovering this type of universal communication as a business model and want to earn money by offering a functional API. This requires more attention than interfaces may have been given in the past.

In this article series, we showed that APIs should actually be a separate component of application development. It makes sense to specify them independently of technology, existing software, and data storage. Developers should focus more on potential customers’ technical needs and be aware of their use cases. This is a major challenge and applies to both the type of APIs discussed here and all other API types.

We’d like to conclude with a quote from Uwe Friedrichsen (codecentric) that sums up this necessity very well. “Creating a good API requires a lot of effort. 😊”