One of the hardest things to do as an API provider is to work within the enterprise environment. This is due, in large part, to the very nature of enterprise structures – often slow to adopt new technologies, fundamentally distrustful of external solutions, and far more insular than most modern corporations would like to admit. This is a shame, as many API developers find that their tools are ignored in favor of custom-built solutions that are almost never as self-descriptive or efficient in implementation.

So what is the average API developer to do? One of the major steps providers can take towards connecting within the enterprise space is actually a solution that is universally positive, and relatively simple to implement. The concept of making your API self-descriptive has some major benefits when it comes to integration into and establishing trust with enterprise solutions, but the benefits of such a system extend far beyond this scope.

Today, we’re going to look at the enterprise space, and look at some common issues API developers and providers come across when attempting to integrate. We’ll discuss the concept of having a self-descriptive API, and establish the value transferred from developers to their enterprise clients. We’ll understand the concept of self-descriptive API ethos from Shelby Switzer, pulling gems of wisdom from her talk given at the 2017 Nordic APIs Platform Summit.

APIs vs Integrations – Convincing the Enterprise

On a fundamental level, the enterprise does not play well and integrate with other systems. The fact is that many enterprise solutions are long-term and custom-built. They have been iterated and mangled over the years, often to update systems that existed long before the computers that now hold the data were even built.

This unfortunately hinders further development outside of the company’s specific, niche implementation. It results in new innovations being ignored in favor of trusted systems that may get the job done, but often inefficiently. In order to rectify this, the enterprise often ignores the concept of utilizing an external API entirely and instead relies on integrations, or custom-built versions of clients that utilize their systems as a base.

The problem with such an integration, however, is that they are not driven by technology or by implementation, but rather by the intentions of those on the inside who’ve developed it.

“People make things really difficult. They have their own ideas, they have their way of doing things. And sometimes, we’ve found in the enterprise, their mentality is that we’re going to do it their way, or they’re not going to do it at all.”

Such a mindset to modern technologies not only hinders further external development, it’s almost resulted in a war of sorts — a constant conflict between enterprise integration and the nature of the modern microservice and API-centric design ethos. This is unfortunate, as standardized web APIs are almost always more efficient and scalable than custom integrations.

4 Reasons Why APIs Are Superior to Enterprise Integration

Not convinced? Here are more reasons why standardizing with APIs wins out against enterprise integrations.

1. APIs are reusable. APIs can be leveraged for more than just a single use application, even when they are a microservice designed to said application. A data routing API or conversion application can be used over and over again, even throughout different parts of the enterprise, reducing code complexity and bloat.
2. APIs are maintainable. They can be maintained much better than a series of integrations in the classical enterprise solution because there’s a single source of data handling, a single codebase (or a group of microservices based upon a common language and schema), and thus a known entity that can be handled for maintenance.
3. APIs are scalable. Whereas APIs are extensible by design, integrations are foundationally limited as to what they can do. This limits what the code can actually do to a narrow scope.
4. Finally, APIs ignite innovation. APIs allow for iteration upon the established codebase, done in cooperation with the enterprise. On the other hand, an integration is not really a cooperation – there may be instances where teams work close together, but in essence, this is still a project defined and limited by the enterprise itself within an extremely confined set of circumstances. This is not negotiation – this is dictation.

Adapting to the Enterprise Environment — The Bad Solution

In many cases, solving the distrust between developers and enterprise managers is only half the answer. In other words, not only does the enterprise not trust the API, it often considers implementing the API to be too complex, to be placing too much in the hands of an external developer, and most importantly, a system that has to be learned and understood.

Documentation is often seen as the solution to this problem, but it’s actually a symptom of it. The only reason documentation would be required (not provided, but required) is if the API itself is so complex or massive that it confirms the negatives perceived by the enterprise and is thus required for its utilization. Documentation is of limited value to external technical teams who we are trying to convince with the simplicity of our APIs and implementations. As Switzer sees it:

“The people that we work with [in the enterprise space] don’t care about documentation. […] The clients just couldn’t care less, and their tech teams will never use it.”

Making a Self-Descriptive API

With all of this in mind, we can begin to see the value of the self-descriptive API. Such an API makes itself understood through its usage. When leveraged with supplementary materials and integrated with open and common standards, the API almost sells itself.

So what exactly makes an API self-descriptive? How can the API be moulded into a form that is not only attractive to the enterprise, but preferable?

Be Self-Descriptive in Your Data Response

Our first step in making an API self-descriptive is letting it be understood within the context of itself. There is a lot you can do to improve an API data response so that external developers understand your operations without the need for extensive documentation and educational material. Below is an example of the Healthify API, an API that primarily handles health data.

"Item" :
	{
		"Href" : "https//api.healthify.us/patients/2324532",
		"Data" : [
		    {"name" : "id", "value" : 2324532, "type": "integer"},
		    {"name" : "name", "value" : "Kate McCallister", "type": "string"},
		    {"name" : "income", "value" :null, "type": "integer"},
		    {"name" : "address_street", "value" : "1 Lonely Way", "type": "string"},
		    {"name" : "address_city", "value" : "Chicago", "type": "string"},
			]
	}

In the above example, you can see exactly what the data types are, and how they work. The fields each link to where the resource lives. While it’s not verbose — we’re not utilizing commenting or notation — the context of the API is understood in relationship to itself.

“The API documentation that matters most is the response.”

Our end goal is simple — to foster trust in our API. The most efficient way of doing this with enterprise developers is to use self-evident data. External developers must immediately comprehend what is being sent by the API, where the resource is, and what type of data the resource is.

That being said, there is still a use case for documentation, especially when our API ties into other APIs and, accordingly, we don’t necessarily have full control over the way in which we describe our external links. This documentation doesn’t need to be dry, however, and in many cases, as long as the data is well-defined, it will be a footnote in the overall solution rather than a hampering factor for implementation.

Leverage Open Standards

A big part of the enterprise equation is also providing a solution that exists in its current form, and is relatively unchanging. This doesn’t mean we can’t add new features, but our API must be reliable. One of the best ways to ensuring reliability while keeping a platform open to innovation is by building upon open standards.

Open standards are those standards which are commonly accepted, known values that are proven and secure. Common open standards in the API space include Open API, OAuth, JSON, Open ID Connect, SCIM, and many others.

Open standards are akin to seeing a movie from a well-known, historic movie series as opposed to seeing an unknown movie from an unknown director — you know roughly what you’re going to get, and because of that, it’s more or less a known factor.

Additionally, open standards can result in a greater level of security, as these solutions are tried and true. Through this additional security and wider adoption, open standards also result in greater consistency throughout the industry, and thereby elevate the offering on hand in the eyes of the enterprise.

Open standards are often in stark contrast to the enterprise, in which solutions are often self-defined and proprietary. Leveraging self-defined standards and ignoring industry standards results in a slow, inoperable ecosystem — the exact solution we intend to fix with self-descriptive APIs.

Follow Best Practices

As an extension from using industry standards, we should also push best practices and adhere to them religiously. By doing so, common failures and issues can be avoided, thereby ensuring extensibility and scalability in the long-term implementation of our API. All of the arguments that can be made for adopting industry standards are exactly the same arguments in favor of best practices, so to save ourselves a repeated lesson, we should simply say this — if you don’t follow best practices, you’re creating an issue, and while one issue might be manageable, as they expand, they become less so.

Benefits of Making APIs Self-Descriptive

Our prime reason for creating a self-descriptive enterprise API is — predictably — to interact with the enterprise. That being said, there are numerous benefits to adopting the process that should be mentioned.

Adopting a self-descriptive API decreases cost for 1 on 1 support. By having the API describe itself, there’s no need to provide additional support because the API supports itself. The need to provide free and extensive support decreases as the platform becomes more descriptive. While such support can be provided, this can often be provided on a subscription basis.

Adopting this API development philosophy means developer experience is much better than the alternative. Developer users don’t need to read a compendium of documentation to try and figure out the intricate web of calls, functions, and endpoints. In a self-descriptive API, it’s easy to decipher things like method functionality or error origin, as the data is readily available.

Finally, a self-descriptive API creates a flexible system that can be iterated upon without introducing incredible complexity. Because the data is understood in the context of itself, adding new functions and data types is rather simple, and can be understood as part of a greater context instead of understood in isolation and in companion with documentation.

Simply put, adopting a self-descriptive API makes sense in the enterprise space, and creates a product that is easily understood, contextualized, and implemented in the relatively strict enterprise environment. In addition to this, great benefits can be realized that ultimately result in a better developer experience, and thereby a better API.

What do you think of this ethos? Is there a better way to make your API more readily understood? Let us know below in the comments.