Notes on the AWS API
Be liberal in what you accept, and conservative in what you send
Building Better Apps
January 2, 2020
I've spent the last couple of days working on some reasonably complex AWS integrations and yet again, I've noticed how well it all hangs together. Any time I've had to get seriously stuck into AWS development I've noticed how easy it is to maintain flow while working on pretty complex stuff. Normally when I'm working for the first time on a new area of a third-party SDK I find it almost impossible to maintain any kind of flow state. You find yourself flicking between your debugger, the sad excuse for documentation, POSTman, any testing tools and Stack Overflow in a vain attempt to wade through the mud. I won't mention any names here but we've all been there.
But with AWS, this experience has for me been entirely different and I've been wondering why. Their documentation is clear but hardly outstanding and there isn't a huge amount available on Stack Overflow. But for me there are two things that stand out. Firstly, they have an extensive SDK for most of the popular languages that is well documented internally and seems to just work. But the main thing is that they appear to be pretty liberal in what they accept as input. This is really key when it comes to helping users make progress.

Hosted Zone IDs

My recent journey into AWS has been to do with setting up DNS resource records and as such, you need to pass around zone IDs quite a bit. This when you'll notice that whenever you list your hosted zone IDs you get back and ID prefixed with the text "/hostedzone/". I'm sure there is some internal reason why this is there but with most SDKs you'd find yourself faced with a choice that may or may not be documented with 100% . To use the zone ID, you may have to strip off the prefix. In the worse case you might find some calls that require the prefix and others that don't.
However, with the calls I used, I didn't do anything - just used the Id as is with further interactions and it all worked out fine. Normally, I'd have left this and moved on but I decided to check what would happen if I did strip the prefix. And then I discovered that it was perfectly happy with that as well. I love this kind of behaviour - it was perfectly reasonable for a programmer to either strip or leave in the prefix so the underlying API is happy to work in either case saving people loads of wasted time.

Pattern of Behaviour

I've seen this type of behaviour when using a range of AWS endpoints through a few different platforms. Once you've got the right documentation, it's like you're pushing an open door. It doesn't barf when using weird CURL headers, the access control rules are clear and consistent and the exceptions and error messages tell you exactly what you need to do. I can see myself doing a lot more work with the AWS SDK - maybe they just think the same way I do.