In the rapid changing world of Software Development, there’s little time to learn the vast amount of new technologies and services available. Many companies are fiercely fighting for clients to use their services, which provides a nice variety of options when you find yourself looking to solve a problem, but at the same time leaves them with little margin for mistakes.
I’m surprised by the huge amount of these companies who don’t follow conventions and best practices when offering such services. They often advertise a high quality, robust, reliable and error safe API, but when you get “hands on the code”, all this perks you were sold account for nothing as their interface is such a mess, and you end up spending a high amount of valuable time trying to write an integration.
The problem starts when they try to be clever (but it’s actually laziness in my own words), and implement API endpoints their own way, following what the developer at that particular moment thought it was right. They justify names and structures outside the conventions based on arguments like “it will be explained in the documentation” or “once you see the data coming, it’s obvious how it works”. But that’s a mistake, documentation gets out of date, teams forget about it and you end up with either a fair amount of outdated documents, or a fair amount of time lost trying to understand what’s going on.
Such problems don’t even start to cover endpoints that break when a change is introduced into these custom objects, which could be avoided with automatic testing or by simply following guidelines and standards.
That meaning, if you’re exposing a REST API for your clients, please follow naming conventions at the very least. That will make life easy for everyone. Your team will spend less time explaining to the client what services are available, and developers on the other side will be happy with a nice, intuitive and easy service integration.
Particularly, on my daily basis, I will almost always choose the service that looks cleaner and well written. I don’t have to study their documentation to know (or assume), what they do and what kind of tools I have to my disposal. Also, that gives me an insight of the developers on the other side. If they worry about following conventions and clean code, chances are they also thought about security, performance, scalability and all these other important aspects.
In conclusion, use REST, JSON, HTTPS, Secure Tokens, naming conventions, automatic tests, canary pages etc. Ensure the interface of your service to the world is as good as you claim your service is. Make a developer happy today.
NOTE: Published originally on LinkedIn on July 25, 2016 and migrated here on Jan 13, 2021.
