API Style Guides and the Quest for Web Service Consistency

In an increasingly complex world with equally tangled problems, a simple solution is a good solution. I’ll give you an example:

I want to listen to (not read) articles from the internet while I’m out in the sun. They’re freely available, but how do I turn them into audio files to enjoy on a mobile device?

The first and quickest solution is to find a product that solves this very problem for me. Audible comes to mind, but I want blog posts, not books, and I like the option of choosing any written content.

Well, I can probably build a program from scratch to do that. It would just mean that I’d have next to no free time for a week or two. That’d be the opposite of simple.

The compromise, and the option I went with, is to build the app from scratch but use functionalities from public APIs. In the end, this was probably the very best option because I didn’t have to pay for anything, and it took me less than an hour to create.

The moral of the story: APIs make a developer’s life easier. Or at least, that’s what it should do. But with mismatched APIs, each with its style and quirks, you may end up making things worse.

So, what do APIs need to actually do their job and do it efficiently? A style guide!

Why? Keep reading!

What is an API style guide?

As the name infers, the style guide is a set of suggestions (or rules, depending on the organization) meant to direct API development according to the users’ needs and wishes.

These documents are usually prepared by groups who intend to develop several APIs as part of a complex system. If you’re planning to make a single API, you can skip it to save time. For more, though, it’s necessary if you want to avoid a fustercluck.

Style guides are first and foremost used for internal APIs within large organizations. For these companies to decide to build their own solutions, it’s most likely a very particular need to fulfill. As such, the style guide ensures that the API stays on track.

For public APIs, style guides are less likely to appear, and that’s a shame. Guides ensure that best practices are followed and make life easier for developers since it provides more uniformity and common logic among APIs.

Ok, that’s all well and good, but what exactly goes into a style guide? What does it look like, and who is supposed to use it?

What your API style guide should contain

In essence, the guide should hold all the information the developers might need to make the most focused and best possible API. Depending on the objective, some of the following elements may be very important or not even present, so take this list with a pinch of salt.

1. The architectural style

First and foremost, you’ll likely want to adhere to an architectural style. In the case of web services, you’ll probably want a REST API. So, make sure you mention the constraints that need to be present within the application programming interface.

The most well-known API designs are:

• REST
• RPC
• GraphQL
• Falcor
• SOAP
• gRPC

2. Endpoint naming conventions

Once an endpoint is named, it’s unlikely that you’ll ever change it. For a single API with a single endpoint, this step may seem irrelevant. But once you release several web services, all with their separate endpoints, it can get confusing fast.

The idea isn’t to come up with endpoint names right at the beginning. You have to set a naming scheme that the team will follow. This way, each endpoint has an expectable and logical name.

3. Versioning principles

Updates are tricky for APIs. Adding something new might not be a big deal, but changing predefined notions or functions can sabotage the users, forcing them to change their own code too. That’s called a breaking change.

Obviously, you should avoid such situations whenever you can, but it’s not always possible. The next best thing is careful and thoughtful versioning. By setting ground rules on how changes can be managed and making those principles known to all, you can more easily transition both the API and its clients to new versions.

4. Error Codes

Most API communication works on HTTP protocols and, as such, uses HTTP status codes as signs of successful or unsuccessful requests/responses.

Many developers take this fact as a sign that they don’t have to put any work into customizing the API’s error codes. That’s not just false, it’s annoyingly incorrect.

Imagine yourself sending your credentials, authorization, method, and some data only to receive a 400 “Bad Request” response. Ok, fine, but what exact part of the request was bad??

Try to offer some explanations, specifically what caused the error. An internal code is a good start, but if you want to truly make errors easier to manage, add instructions/advice to your error codes. A “you may want to try…” accompanying the error goes a long way.

5. How to handle authentication and authorization

APIs have been considered a cybernetic vulnerability for companies everywhere and with good reason. Since APIs are built for communication and data transfer, they’re prime targets for clever hackers. Any security oversight could spell massive data breaches and problems down the line.

The style guide has to be crystal clear on how to implement authentication (who you are) and authorization (what you can do) to ensure that both devs and users are safe from harm.

Here’s an example of a popular authorization framework: OAuth 2.0.

While making a style guide, don’t skimp on details or rely on others do be smart. Mistakes made here might not be just an inconvenience, but a gaping hole in your company’s database. So, you know, be careful.

Why you should make your own APIs

Many look at APIs and think “only big corporations make those”. Yeah, big enterprises have their internal APIs, and companies like Google offer public APIs for a price. But you don’t need a big team or big budgets to make APIs.

In fact, you don’t have to be a business to even benefit from APIs. I’ve had a lot of fun looking into different ways to use APIs to your advantage. Here’s my code on the text-to-speech project I mentioned at the beginning of the article, and here’s a sneaker auction scraper I made.

What I like most about APIs is that they give you the liberty to be creative. You stop focusing on implementing functionalities and start thinking about how to take them to the moon!