APIs provide multichannel delivery

Many companies use microservices to encapsulate the core capabilities of their organization in a way that is scalable and reliable. Microservices correspond to important functional elements of your company’s IT component. But that’s only half the battle. You also need to figure out how to provide these opportunities so that with their help it would be convenient to solve the actual challenges facing your business. This is where APIs come into play.

APIs — Application Programming Interfaces — play the same role for a machine as a graphical interface does for users of your company’s information systems. APIs are often used to mix different capabilities into a consistent and affordable solution. For example, your company might use services to handle transactions related to customers, accounts, and sales. Each of these services was carefully designed, programmed, tested, then released and built into your company’s infrastructure; the service provides functionality that is critical for your business. One day, you need to create a new user induction solution – and that solution should work on a wide variety of devices and platforms. So, let’s start using the API to its fullest.

A single API tailored for solutions — for example, an API for introducing users to a system — can be designed to bring critical interactions and task flows critical at this familiarization stage to the surface. This is where an API comes in handy, which allows us to blend different customer, account, and sales functionality into secure, powerful and accessible user interfaces for a wide variety of target audiences within your company. For example, salespeople can log into the system from a browser, office admins from PC applications, and potential customers from smartphones and tablets.

We can say that the API is a kind of “glue” that holds the elements of the program together, an intermediary layer through which your internal services and external service consumers interact. It is the API that is the means for distributing key functionality in such a way that it can be used by service consumers whose task is to create important mechanisms for interacting with the user on a wide variety of hardware platforms. These customers may include other teams in your office, colleagues with whom you communicate remotely, key business partners, or even remote front-end or design staff. 

Design Thinking and API

Most companies know how important it is to take the time to design the user interface for their applications. Because you know that good design is popular with users, increases brand loyalty and allows you to promote new business. At the same time, poorly designed interface can irritate customers, harm a brand, cut revenue and take away opportunities. The same is true for API design.

If the API is done poorly, then it will be difficult for developers to understand it, because of this they can introduce errors into the system, and provoke unnecessary costs for fixing bugs and modifying the infrastructure. However, if the API works well, then it is easier for the employee to work with it effectively. The time required to create a stable solution is reduced, the team is even incentivized to deliver fresh, innovative solutions that would help clients and colleagues. API design is such a big deal that Werner Vogels, Amazon’s CTO, even said:

We knew right away that designing an API is a very important task, because we will only have one try to get it right.

It is the high-quality APIs that help attract partners to your digital ecosystem and simplify the internal corporate transformation of your business. The ability to take the time to do everything right, and, in the long term, is an important skill that we trace exactly to those companies that have learned to use their APIs at full capacity. 

The Ultimate API Design Tips

It’s important to get your API right – and for many reasons. After the release, it is impossible to roll back the API back. When customers and key businesses depend on your API, changing the dependency can damage other elements of the system, break important functionality, and nullify your investment and time spent. There are other important things to keep in mind when implementing an API program. I will only mention a few.

There is no canonical API

It is a mistake to try to “advance” a canonical API design for your entire company. Just trying to implement some of the objects and data models across the enterprise, that is, trying to create a single API that would take into account all aspects of your organization, now and in the future, is most likely a dead end. It is far better to provide your developers with guidance and constraints to help them avoid mistakes, be creative, and apply domain knowledge to create amazing APIs that will appeal to peers and partners alike. 

Implementation process: cutting off all unnecessary

Since an API is just an interface, not functionality per se, you need to be able to design, implement, test, and deploy an API in a matter of days or weeks, not months. We know how companies are trying to mitigate risks when creating APIs by making the API easy to test in advance, automating the release process so that the API itself is less costly and easier to compose. 

Emphasis on interaction, not integration

Another key aspect that successful companies master to perfection is the ability to teach development teams to build in the API the ability to interact with other elements already at the design stage. These organizations explain how to work with their APIs, so these APIs are not only easy to understand, but also easily linkable with other APIs from that company. Aiming for broad interaction is more important than designing tight and tight integration. 

Three things you can do today

This kind of work, like any important change, takes time. However, you won’t have to wait long for success. I’ll tell you about three measures that I have seen in various companies, and which you can take today. 

Adopt your own API creation practice

A key ingredient to the long-term success of your API program is to develop technology-agnostic API design practices. Make sure that such a program does not depend entirely on the latest fashion in programming, using libraries or platforms. To do this, it is most convenient to rely on the “API first” paradigm.

API first means that we design the API first, and only then think about the implementation details. Basically, the business part is the same, no matter what technology you use to implement the API: be it SOAP, CRUD, REST, gRPC, GraphQL, or any other popular thing. In fact, a well-designed program is likely to provide recommendations that are relevant to different technology stacks, thus helping your team assess the potential savings and maintain consistency across future platform releases. 

We guarantee low risks when creating an API

Having properly designed the API, it’s time to put it into reality. At the same time, I recommend starting with a sketch, then moving on to the prototype and assembly pattern.

API sketches are exactly “sketches”. Small rough “blueprints” to help you get an impression of how this API might “taste and color” from a developer’s perspective. An API sketch should be done in hours, not days. Moreover, on its basis, a project should be obtained that can be shown to colleagues and stakeholders, so that the first round of discussion and the first modifications would cost practically no expenses. I like to use Apiary’s API template for this. It uses a simple markup language to simulate a production API server in minutes. The specific tool is not that important; practice is important. Sketching helps you do some cheap research before you start preparing a full API.

I’ve noticed that tools like Swagger / OpenAPI are popular in prototyping. Prototypes are much more elaborate models of your final product. They are like movie sets. If you don’t look closely, you see an almost real scene! The team should be able to prepare a detailed prototype in just a few days. Such a prototype should be free to connect to test tools, virtualization services, and other platform elements so that you can directly observe how it interacts with your system. Prototypes are needed in order to test them. They are your last line of defense before you have to spend money building a real working API.

This is where the build phase ends. Next, we have to formulate a work plan, set deadlines and start turning the prototype into a product. We needed a sketch and prototype to work out the details, identify bugs, etc. The assembly process itself is not that interesting. You just need to show the finished result every day, implement the API step by step until the work is ready. Many companies strive to build APIs within 90 days. 

Three pillars of API management

Finally, looking beyond the design and implementation of a single API, the organization needs to maintain a viable API program and apply generic API design guidelines that all teams will know. Concise regulation allows you to control API development across the enterprise without getting too oversaw of implementation details. 
Eric Wilde, my colleague at the API Academy, highlights the importance of “managing the landscape of your APIs,” that is, regulating the three key elements of an API program: protocols, formats, terminology.

Protocol regulation is a clear indication of which application layer protocols the API team should support when preparing new releases. Most companies assume that all new APIs should support HTTP. Some also specify other, optional protocols, such as MQTT, Thrift, and other binary protocols. The most important thing here is to inform all teams in advance: “If you want to guarantee interoperability of your APIs in the future, you must use these protocols.” To fulfill this rule, it is desirable to use a continuous delivery pipeline.

Format regulation means that you need to agree on what formats data will be sent between services. Almost all browsers expect a response in HTML format – just like at the level of your API, you need to decide in what format it will interact with the entire ecosystem. Most companies prefer simple formats like JSON, XML, or CSV, but their message models lack key metadata such as object names, link names, and input forms — which are essential for long-term interactions. On the other hand, I also know companies that use more advanced formats such as HAL, Siren, and Collection + JSON for HTTP-based APIs. Many organizations use protobuf and similar formats for binary interactions between services. No matter which format you choose,it is important to test it in your assembly pipeline, making sure that only APIs that are fully compliant with the regulations are delivered to production.

The third whale of API management is terminology. In this case, we are talking about control over the names of data points and identifiers of actions used in the exchange of messages between services. By adhering to the terminology, an organization can be confident that new services will be well received by existing ones. Remembering the “common language” proposed by Eric Evans for Domain-Driven Design (DDD), I note that the terminology you have chosen is needed in order to talk about the most critical business operation. It must be tricky to release a service to production that uses “completely new” data field names and action IDs. On the contrary, the elements of the assembly line must be checked against the general terminology accepted throughout the company,and APIs that are out of this terminology should not make it into production.

By learning these principles of API First, Sketch-Prototype-Build, and the Three Whales of API Management, your team will be able to use their APIs to their full potential without compromising runtime stability.