Of course, when I say platform I could say service APIs, or SDKs, or tools. Or everything together. In the end, what I really want to say is that building stuff for developers is hard. We tend to be a community that is hard to satisfy, if only because we rely on other developers to build stuff so we can build stuff, and in this scenario, the Developer Experience is a real thing. As I write this post, I am thinking about APIs such as Stripe, Twilio, GitHub, Shopify or even more serviceful cloud platforms such as AWS and GCP.
Sometimes we just don't like, and even criticize, the type of services available on a development platform or even the contracts offered by a concrete service API. We tend to forget that, although we are not aware of them, there are trade-offs that the API team had to make in order to come up with that version of the API. As Eric Elliot once said:
Engineering tradeoffs and stupidity are often indistinguishable if you're unaware of the tradeoffs
The importance of Backwards Compatible changes
Having said all that, there is something that really challenges the Developer Experience: Backwards Compatibility. And I have a lot of questions I don't have the answers for:
- How do you practice pure Agile (ship fast, fail fast) when you are building a platform or developer tools?
- What if you shipped an MVP of your API and you find out that you have failed miserably, but you have hundreds/thousands of developers already using it?
- Is it possible at all to have backwards compatibility and avoid deprecating APIs?
- Is it possible to do that while keeping things simple for new learners while being consistent for existing developers?
I told you, it's not easy. On one side, If you practice versioning and you keep everything, then your platform may become an unpracticable service-mess (pun intended, AWS anyone?). On the other side, if you start deprecating your old, failed stuff, your developers will start running away from you as they won't trust you anymore (Google anyone?).
Again, I don't have the answers to all those questions and concerns, but I do have a preference. As an engineer, I have an opinion about what I'd like to see when I am building stuff on a platform, and of course, what I would do if I was building one (which I am, by the way).
Managing the Complexity
As you can imagine, I don't have exposure to all platforms (APIs and services) out there, so in order to illustrate this preference, I am going to pick a few examples I have seen:
- AWS introduced API Gateway in 2015 as a cloud managed service for developers to build and maintain RESTful APIs at scale. It served well to us engineers for years, allowing us to design REST resources and HTTP interactions for our APIs. Then, AWS realized (by listening to their customers) that they made a mistake: allowing fine-grained REST resources and interactions was too complex. Users were using the API Gateway in a more simplistic way and in many cases just using the proxy resource. What did they do? Well, instead of sunsetting REST APIs and infuriating thousands of existing users, they introduced HTTP APIs, a new variant that co-lives with the former service. Today, they still maintain both and there is no signal from AWS indicating they may force us to migrate, one day. This is very similar to Basecamp's Until the end of the Internet policy
- OK but, isn't introducing new services like that very confusing to the developers? Yes, very much. I told you we are hard to satisfy! So how does AWS solved this? Some may argue that in this case, it would be easy to just let new accounts have access only to the new services. But why? The old service is perfectly usable. Instead, what they did was making sure that when you start configuring a service all the necessary configurations are defaulted to the new features/services the platform wants you to use. Defaults matter, and it's a very smart solution to alleviate the perceived complexity. This is how they did it when they started to introduce new features in AWS Lambda service.
If you are using AWS, you probably don't realize that they are introducing new features, APIs, SDKs, and versions of the services every day, even several times per day, with almost zero disruption to you. At least, with zero migration notice or grace period to you, I guarantee that.
How do others manage this? As I said, I don't have exposure to all the APIs in the world, but I can feel that introducing breaking changes or sunsetting services should be the last resort. I know that Stripe is taking a very similar approach, and when they realized that an API sucks and they have to fix it with breaking changes, they introduce a new version so they don't break your stuff. For them, backwards compatibility is also a mandate.
Because Developer Experience is important and it is a real thing.
Top comments (0)