How to build an infuriating API: 3 recent big problems

Recently, I had an experience of using an incredibly infuriating API, and wanted to document some of the issues with this API and how the developer experience in your API and platform can avoid these issues, reducing the need for developers to be in constant contact, and improving the entire ecosystem around your platform.

Point 1: Documentation

Nobody likes writing documentation, yet it’s important. Some basic items such as running a spell check are also greatly appreciated – even just for technical terms (nobody like Ajex instead of AJAX).

Documentation should also go beyond just how to call your APIs too! Document if it’s advisable to cache certain information, document how different tables link to one another (an Entity Relationship Model is always a good help, and tools like PlantUML make these relatively easy to produce!), document how fast APIs are designed to respond in your production environment.

All of this background information really helps build a picture of what would need to be developed, i.e background processes and progress boxes to inform the user of what is happening.

Documentation is really about more than just an auto-generated list of parameters and a Postman collection! It’s absolutely useless giving a spreadsheet which says “BillingAddressLine1” is “The billing address line 1” and for instance, not explaining that it’s required or not to send this item, and if so what formats are accepted.

Or even parameters which are not explained what typically should be set, for instance setting Processed to N (even though a boolean should in theory be used), to indicate the system hasn’t processed data, and not if the consuming system has processed the data!

Also important is to ensure the documentation is correct. All of your work may not even mount to much if the API differs from the documentation.

Point 2: Visibility

An API should not be a black hole. Having an API which does not return a meaningful result is almost pointless. For instance if there is no error appearing anywhere, nobody will ever know something didn’t work and can pile up problems. There is no way to know that there could be 15 other end-users who could be trying to use your platform, and are unable to complete. The way you find out is when the client is on the phone complaining, and is probably quite annoyed – an unhappy client who is then unlikely in a good mood to spend further money with you!

Another problem is with creating something, not returning a useful identifier, or any identifier at all. This makes it incredibly difficult to reference later, especially when in most cases when you create data you’ll want to reference it again later!

It’s understandable you may have background processes, but not having any visibility into if they completed or not is incredibly challenging. For example, if a background process fails, if there is no notification, then nothing can be done to unblock a problem before a customer is too upset.

Again, if these background processes create an entity, being notified of the new identifier is usually very useful, and not having to create excessive load just looking and hoping it’s completed is not a great look.

Point 3: Consistency

Even with bad documentation and problems with the responses – having a consistent API is important too. Changing of names of fields between retrieving and sending data is incredibly frustrating, and makes building forms to do basic CRUD operations much more difficult usually for both your internal developers and anyone consuming your APIs!

Consistency also means you are using the same functions for similar operations, meaning less code in total to be written, less code to be tested, and more importantly less code to go horribly wrong!

Conclusion

We’ve covered some basic points, and some items to hopefully not do for your own APIs. All in all, more companies should also be asking the developers who consume their APIs for anonymous feedback and explain the issues with working with APIs.

Hopefully, as more systems get interconnected, APIs that are build are better documented and much better built to be properly consumed and integrated.

If you have an API which needs integrating into your web application, or advice and consultancy around your APIs, please don’t hesitate to get in touch.

Further Reading

Further reading includes “Building APIs You Won’t Hate” by Phil Sturgeon from 2019, although much of the content still is relevant in today’s world – perhaps even more so with many projects being completed without the human oversight and quality!