How AWS dumps the mental burden of inconsistent APIs on ...

If I need to look up the docs for every single API, or even just **feel** like I might have to look them up, it detracts from my actual work: solving business problems. Inconsistent APIs cost more time to implement, and they increase the mental load on developers. But they might also reduce the quality of the applications using them. Worst case scenario, this can lead to a bug in production, with serious time and effort required to fix it. And that cost adds up. … What I found was that there’s no consistency between different AWS services, between related AWS services, and even **within** a single service’s API. Let me give you an example of each. … When we include Kinesis Video Streams (KVS), it gets even worse. This service also has the `StreamARN `and `StreamName` fields, but you can get them through `ListStreams` **and** `DescribeStream`. And for KVS, the creation timestamp is stored under yet another name: `CreationTime`. ### Inconsistency within an AWS service Inconsistency within a service is the worst type of inconsistency because, ostensibly, a single service is maintained by a single team. It’s a real problem for developers. You can make a mental note that when talking to a different API, you might need to use a different syntax. But when various calls within the same service are inconsistent, you can never really rely on muscle memory, ever. One of the more painful examples of this can be found working with REST APIs in API Gateway. This is a complex service, so it can be forgiven for having a complex service API. It has dozens of resources, including API Keys, Methods, Resources, Usage Plans, and Documentation Parts. Each of these resource types can be retrieved in singular form with a request like `GetAuthorizer` and in plural form with a request like `GetAuthorizers`. (Side note: That’s a whole new variation on the `Describe `and `List` standard.) … This `items` versus `item` example can lead to bigger issues. If you’ve seen 20 examples of an `items` response, you’d be forgiven for assuming the 21st also returns `items`. An automated check or test deployment might surface this bug, but it might also miss it. Fixing it after it’s live can cost significant time as well as your reputation. … ### Amazon CloudFront The worst service API I’ve encountered so far is CloudFront. This API is inconsistent compared to other services, is inconsistent within its own domain, and returns responses in such a broken way that it should be considered a bug. First, the method-naming and response format. CloudFront has `**Get**`, **`List`**, **and** `**Describe**` calls. The `List` operations all return a dictionary with an `Items` key, which is a list: … This is bad. This will break any parser because an empty string is not valid JSON. It also means that all of these calls have two different types of output: a dictionary or an empty string. As a developer, it means you have to inspect the result length before passing it on to the parser. You can’t even write a simple try-catch block because then you wouldn’t be able to differentiate between a failing API call and zero results. This is not only bad design, but once again, it’s inconsistent with all the other services that at least offer reliable output. … Despite the problems that inconsistent APIs create for AWS customers, the burden will continue to be on us developers for the foreseeable future.