APIs and the Cloud

| February 23, 2022 | in

Application programming interfaces (APIs) communicate into software. If user interfaces are ways for humans to interact with software, then APIs are ways for software to communicate with other software. As we write applications, our software makes extensive use of APIs. Sometimes those APIs are purely at a platform level, maybe file read and write. Sometimes those APIs are product specific. Regardless, we are using APIs and many of them.

The concept of APIs in the context of the cloud will immediately become cloudy (see what I did there). Back when all we wrote were applications, the APIs were purely defined in code. Today, APIs are often defined as the interface between two software systems. Today’s APIs are often web service calls. Web services are a broader topic as it includes the code interface and discussions of protocols and transports.

What are we looking for in a good API?

Interfaces to our systems matter
Writing tests for your interfaces will force you to become the first consumer
Prefer stateless interfaces
Obey rules of the platform
Minimize coupling between services

We need APIs to be easy to understand, predictable, and useful. Many APIs will fail one of those three requirements.

The most basic failure is that many APIs are not easy to get your head around. They are a mess of many different endpoints and calls.

When looking at an API, each endpoint looks very different from the other endpoints. This makes it hard to predict how one endpoint will behave even if you understand another endpoint.

Sometimes APIs are just not useful. They are missing many key features necessary for the API to solve real-world problems. These sorts of issues with an API often get sorted out over time as the API expands, but many new APIs are missing key features that make interacting with it difficult.

REST-style endpoints are probably the most common today. REST lacks definition, but I do like the Microsoft guidelines for them. These guidelines provide a starting point for building a good REST API.