From various conversations I’ve had and posts I’ve read online, I’ve encountered one painfully clear thing: there are two types of APIs, the crap ones and Stripe. Not all of us can reach the divinity of the holy Stripe API and its almost cult status in job interviews and technical design meetings. Still, even we, as mere mortals, have things we can do to improve ourselves, our APIs, and our API consumer’s lives significantly.

This will be a bucketful of hot takes, technical decisions, examples, and opinions so that it will be made into a series of posts focusing on specific parts. For now, let’s look at the bigger picture and try to determine what are some key things a developer could care for either as an implementer or integrator when working with an API. Also, for clarity and brevity, although much of the discussion will be around REST APIs, I will refer to them as “APIs” in general, and many of the standards and best practices of one API type can apply to others. It’s more about the logic and the informed decisions behind implementing a specific design that matters more than the technicality of it.

Also, please note that when I am referring to “Developers” it means both the developers of the API themselves as well as the people consuming it or relying on it. Be it integrators, partners, other team members, senior, junior, or citizen developers. So keep in mind, unless specified, that a developer is anyone and everyone who has some business with the API.

Let’s start by looking at some things that will create an awful, awful, awful experience for the developers. I pray to the almighty Stripe API Celestials that many of these are self-explanatory to the vast majority of developers, but let’s start.

  1. Terrible or non-existent references and documentation. People say documentation is a waste, not agile, old-fashioned, a waste of time, why bother, and other Zoomer takes on the subject. Still, the matter of fact is, unless you know what you’re building towards or building with, you’re just going to be miserable. Undocumented behavior, routes, functionality, variables, query strings, header values, and HTTP codes are not only hard to implement and maintain, but it’s also foolish to even introduce them in the first place, even if you intend to have them as a “one-off” band aid solution.
  2. No versioning. Even if you never, ever intend to have multiple versions available at the same time, you should make use of versioning. Plans change, tech stacks change, but one thing that doesn’t change is some dodgy integration someone made a decade ago that randomly failed once you introduced a significant change in your unversioned API.
  3. No consistency in your responses. Imagine some routes (or Stripe-forbid the same route) return a collection as a JSON object or as an array of objects, interchangeably, based on something that’s not obvious (such as a parameter to request it as JSON, XML, or something). How would anyone parse that? How does anyone introduce new functionality to it?
  4. Low availability. Imagine introducing the world’s most useful API, for example, something that returns my Paladin’s raid logs, and it’s only available every other Monday, as long as it’s not raining. There’s an implied “promise” that an API will be available and responding to requests (up to some hopefully known limit) for as long as it lives, and the AWS EC2 instance charges your credit card successfully. If it’s unavailable, at least ensure the user knows why.
  5. Low reliability. APIs are software, and software has to work; the more bugs and catastrophic failures your API experiences, the less happy people will be with it.
  6. Inconsistent design. Suppose different parts of your API are designed and operate differently. In that case, it can be a very confusing experience for a developer and potentially even lead to a sensory overload.
  7. No support. This is not limited to having an online chat, contact form, or phone number, but it’s more about the help you have available for the users. In addition to direct contact, there are more ways you can support someone; documentation could be one, but also having a community of developers available, proper error handling and error responses, failing gracefully, providing enough information to an end user, contract tests. Remember that APIs are generally challenging to debug once they experience some failure.

Thankfully, it’s not all doom and gloom, and there are other reasons a developer can hate your software. So, let’s quickly review some ideas that might inspire you or even help you and your API reach Stripehood.

  1. Create a style guide. It doesn’t have to be perfect, but similar to how you would introduce coding standards to your code, you can do the same with your API. Part of it can be done by simply documenting and following a set of design rules, but some tools can help you lint your API and become part of your CI/CD pipelines. Here are some resources I’ve used before: Stoplight and Redocly, but there are several other tools available as well.
  2. Introduce peer reviews. As cliche as it might sound, one of the most effective methods to introduce consistency and improvements across product APIs has been getting developers to openly and honestly review each other’s work and determine what and how we can improve. Regularly reviewing your APIs in production or development can highlight things you did exceptionally well or areas of improvement, especially if it’s done specifically from a consumer’s point of view.
  3. Get familiar with your audience. One thing I have noticed, especially with products that have been developing for months to years, is that the developers often lose sight of their intended audience. For example, many teams might start building specifically for other internal teams familiar with your product’s architecture and technical concepts. Still, when released, the end user is completely oblivious to them. Similarly, you might be too fixated on the end user’s experience when you’re simply developing something another internal team will integrate with, say, billing or authentication.
  4. Introduce analytics and collect feedback. It is always interesting to see the success rates of calls against your API, especially for new users. Try to determine if there are any pain points. Is your authentication model working? How many steps must a developer take before reaching the desired result?
  5. Try using your API. As part of a hackathon, I had to use my own company’s API product, and those couple of days gave me more insight and ideas about our APIs than hours upon hours of technical meetings ever did. So, I highly encourage you to go out, start with an empty project, and attempt to integrate and use your API.

That concludes this initial overview post. New, focused posts will be coming out shortly as they are ready. It should be once a week or so, depending on the subject and the amount of coding involved. Please leave feedback, suggestions, and comments below; I would love your thoughts. I live for technical discussions.

Also, if you are specifically interested in some subject I haven’t covered yet, feel free to reach out. I am always happy to provide my thoughts.

Once again, thanks for reading, and I hope you come back for more posts.