The Power of APIs – InApps Technology 2022

As a member of the API Academy, I have the opportunity to travel around the world meeting amazing people. They’re working on fantastic projects in all sorts of companies — from new startups to mature global enterprises. Incredibly, no matter where I am, no matter who I am talking to, many of the same ideas, practices and experiences come up. Three that I consistently hear about are microservices, APIs and a culture of innovation. All are employed in the name of advancing digital transformation of an organization.

In this article, part two of a three-part series, I will share what the API Academy is learning about these powerful trends and some of the techniques companies are using to make the digital transformation more than a buzzword. In the previous article, I focused on the importance of microservices and three things you can do today: 1) adopt continuous delivery, 2) enable engineered deployments, and 3) reduce the work-in-progress queue to speed time-to-market. These three key habits can help your organization take advantage of the power of microservices.

In this follow-up piece, I’ll share what companies around the world are telling us about the role APIs can play in empowering teams and enabling the organization to quickly craft timely, stable and cost-effective solutions for a wide range of distribution channels including browser, mobile and desktop. And I’ll offer three common practices we’ve found other companies are using to move them along in their digital transformation journey.

APIs Enable Multichannel Delivery

Many companies are using microservices to encapsulate key capabilities within the organization in a way that is scalable and reliable. Microservices represent the important functional elements of your company’s IT. But that is just part of the story. You also need the ability to expose these capabilities in a way that makes it easy to solve current business challenges. And that is where APIs come in.

APIs — application programming interfaces — are the machine equivalent of the user interfaces for your company’s information system. Often APIs are used to mix various capabilities into a coherent and accessible solution. For example, your organization may have services to handle customers, accounts and sales activity. Each has been carefully designed, coded, tested and released into your company’s infrastructure; offering functionality critical to your business. Then one day you need to create a new customer onboarding solution — one that works on a wide range of devices and platforms. Now it is time to use the power of APIs.

“We knew that designing APIs was a very important task as we’d only have one chance to get it right.” — Werner Vogels, CTO of Amazon

A single, solution-oriented API — for example, the customer onboarding API — can be designed to surface the important interactions and workflows critical to a successful onboarding process. One that works for it is the API that can mix the various functional elements of customers, accounts and sales activity into a safe, scalable and powerful user experience available to a wide range of audiences within your company such as for sales staff from their browsers, for in-office admins from desktops apps and for potential customers on their handheld and tablet devices.

You can think of APIs as the “glue” that pulls things together — the mediator between your internal services and your external service consumers. APIs are the way to distribute your key functionality for use by service consumers tasked with creating important user engagement experiences across a wide range of hardware platforms. Those consumers might be other teams in your office, colleagues at remote locations, key business partners or even third-party, front-end and design teams.

Design-Thinking and APIs

Most companies know that it is important to take the time to design user interfaces for their applications. They know good designs can delight users, improve brand loyalty and drive new business. At the same time, poor interface designs can annoy customers, damage a brand and reduce revenue and opportunities. The same is true for API designs.

Poorly-designed APIs can make it hard for your developers to understand them, possibly introduce errors into the system and may add needless costs in bug fixing and infrastructure modifications. But well-designed APIs can empower employees to work effectively, reduce the time it takes to build a stable solution and even encourage teams to create new, innovative solutions that help customers and fellow employees. API design is so important that Werner Vogels, Amazon Web Services’ chief technology officer, says, “We knew that designing APIs was a very important task as we’d only have one chance to get it right.”

It is the power of APIs that brings partners to your digital ecosystem and drives your own internal transformation. Spending time to “get it right” and build for the long term is an important practice we see at companies that are good at leveraging the power of APIs.

Key API Design Advice

Getting the APIs right is important for many reasons. Once you release an API it’s impossible to take it back. When customers and critical business units take a dependence on your API, changing it can break other parts of the system, undo important functionality and destroy key investments in time and money. There are other important things to keep in mind when implementing your API program. Here are just a few.

There Is No Canonical API

It is a mistake to try to do an “up-front” canonical API design for your entire company. Just attempting enterprise-wide data and object models — trying to create a single API model that accounts for any and all aspects of your organization for now and into the future — is unlikely to succeed. Instead, provide all your developers with guidelines and constraints that keep them from making mistakes while allowing them to apply their creativity and domain knowledge to build APIs that delight other team member and partners.

Streamline the Implementation Process

Since APIs are just the interface, not the actual functionality, you should be able to design, implement, test and deploy APIs in a matter of days or weeks, not months. We’ve seen companies focus on reducing the risk of creating APIs, making it easy for them to be tested early, and offering a release automation process that reduces both the cost and the risk of putting together APIs.

Focus on Interoperability, Not Integration

Another key element we see successful companies do is to teach teams to focus on building interoperability into the design itself. These organizations provide API guidance that results in APIs that are not just easy to understand but also easy to “mash-up” with other company APIs. Aiming for wide interoperability is better than designing in narrow, tight integration.

Three Things You Can Do Today

Like any important change, this kind of work takes time. But you don’t have to wait very long to experience success. Here are three things we’ve seen at a wide range of companies that you can start to do today within your organization.

Adopt an API Design Practice

A key element to long-term success for your API program is to adopt a technology-agnostic design practice. Tech trends come and go, but your APIs will be around for a long time. Make sure you don’t build your entire API program on the latest fad in programming, platforms or libraries. The best way to do this is to rely upon the “API-first” paradigm.

“API-first” means design the API before you worry about the implementation details. A business process is essentially the same whether you implement that as an API using SOAP, CRUD, REST, gRPC, GraphQL or any other popular technology. In fact, a well-constructed design program will likely produce an interface guide that can be implemented on more than one technology stack, thus helping your teams realize both cost savings and design consistency across platforms and successive generations of technology swings.

Enable Low-Risk API Creation

Once you have a well-designed API, it is time to turn that design into a reality. For this, we recommend adopting what we call the sketch, prototype, and build pattern.

API sketches are just like they sound. Small, rough “drawings” to see how the API might “look and feel” for developers. You should be able to build an API sketch in a matter of hours, not days. And it should result in a design that you can show to critical stakeholders or teammates to solicit a round of feedback and modification with almost zero cost. I like to use Apiary’s API blueprint for this. It relies on simple markdown language to mock up a working API server in a matter of minutes. The exact tool is not important, but the practice is critical. Sketches are your way to do cheap explorations before working on the production-ready API.

For prototyping, we see companies using tools like Swagger/OpenAPI. Prototypes are much more detailed renditions of your final product. But they’re missing key functionality. They’re like movies sets. If you don’t look too closely, they look like the real thing! Your team should be able to work up a detailed prototype in a matter of a few days. This prototype should be able to be connected to test tooling, virtualization services and other platform elements to allow you to see just how it will interact in your system. Prototypes are meant to be tested. They are your last line of defense before spending time and money on building the actual production-ready API.

And that leaves the build stage. This is where you pull together a work plan, set deadlines and work to realize the prototype. You’ve used the sketch and prototype stages to work out details, expose bugs, etc. The build process shouldn’t be very exciting, either. It is just a matter of showing up for work every day, working through the API design, and releasing on a regular basis until the job is complete. Many companies we talk to aim for API builds that can be completed in less than 90 days.

Support the Three Pillars of API Governance

Finally, rising above the work of designing and implementing any single API, organizations that have healthy API programs also have general implementation governance guidelines they share with developer teams. Solid guidance makes it possible for enterprise-level oversight without the need for exerting control over implementation details.

A key habit in what my API Academy colleague, Erik Wilde, calls “managing your API landscape” is crafting enterprise-level guidance for three key elements of your API program: protocols, formats, and vocabulary.

Protocol guidance means establishing clear directives on which application-level protocols API teams need to support when crafting new releases. Most companies say all new APIs must support HTTP. Some also add optional support for protocols like MQTT, Thrift and other binary protocols. The key here is to tell all teams ahead of time, “If you want to ensure your API’s future interoperability, you need to be using these protocols.” You can use the continuous delivery pipeline described in the previous article in this series to enforce this guideline too.

Format guidance means identifying message formats used to send data between services. Just as all browsers expect responses in HTML format, your APIs need established format(s) to interoperate within your ecosystem. While most companies select simple formats like JSON, XML or CSV these message models are missing key metadata information — such as object names, links, and input forms — needed to ensure long-term interop. Instead, we see companies adopting advanced formats like HAL, Siren, and Collection+JSON for HTTP-based APIs. For binary interactions between services, we see organization standardizing on protobuf and similar formats. Whatever formats you choose, it is important to validate them using your build pipeline to make sure only governance-compliant APIs are released into production.

The third pillar of API governance is vocabulary. This is the control of data point names and action identifiers within messages sent between services. Maintaining vocabularies is the way organizations can be sure that new services released into production are already understood by existing services. Like Eric Evans’ “ubiquitous language” from Domain-Driven Design, the vocabularies you use represent the way everyone “talks about” your critical business operations. It should be difficult to release a service into production that just “makes up” new data field names and action identifiers. Instead, elements of the build pipeline should test messages for company-wide vocabulary compliance and prevent non-compliant APIs from making it into production.

Adopting the habits of API-first design, sketch-prototype-build, and the three pillars of API governance can help you and your teams leverage the power of APIs without incurring an increase in risk or reduction in runtime stability.

But How Can All This Help Me Innovate?

The ability to provide core API guidelines for teams can spur innovation at all levels of your IT division. But just providing the technical guides is not enough. In the next article in this series, I’ll review some important patterns and practices we see inside organizations that make it possible to leverage the skills and creativity you already have inside your company.

CA Technologies sponsored this post.

Feature image via Pixabay.