It also has tree-shakeable imports which v2 doesn’t have, and a very extensible looking middleware architecture which I’ve yet to need but good to know that it’s there if I do. The auto-generated docs leave something to be desired, but are passable, with a few extra clicks here and there.
"Superior" by which measure? AWS is making money hand over fist. Companies use AWS because they think it's better than alternatives.
- Auto-generated Typescript documentation that's unintelligible (Lord Jesus help me).
- Weird naming of imported functions (e.g., appending "Command" to the end of imports).
- The need to create instances of requests (commands) and then "send" them to the API vs. just passing an object of options. The irk here is that it breaks the affordances around API design.
For example, using S3 used to look like...
---
import AWS from 'aws-sdk';
const s3 = new AWS.S3({ ... });
s3.putObject({
Bucket: 'some-bucket',
Body: 'data buffer',
Key: 'file-name',---
Now, it looks like...
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client(config);
const command = new PutObjectCommand(input);
const response = await client.send(command);
---
This example is taken straight from docs (https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clien...). config and input are not described anywhere near this example, meaning you have to go hunt for them.
---
The gold standard I reference for API design is Stripe. They have just as complex an API as anyone, and yet, they don't go out of their way to overcomplicate things. For example, this is stupid simple and obvious:
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
// `source` is obtained with Stripe.js; see https://stripe.com/docs/payments/accept-a-payment-charges#we...
const charge = await stripe.charges.create({ amount: 2000, currency: 'usd', source: 'tok_amex', description: 'My First Test Charge (created for API docs)', });
---
Not only is the API descriptive of what it's doing by design, they had the wherewithal to explain where the missing piece can be found. Contrast that with Amazon where they give you a half-assed example and you have to go on a goose chase to find the params/options for the request. Why?!
The above changes look like a wank or job protection, not any form of well-considered improvement. Couple that with turning the docs into a maze (as opposed to just saying "here's the function, here are the required/optional params, this is what a response looks like) and you realize that the person responsible for this just greenlit it without any question as to "why are we doing this?"
Yes, I'm being an asshole about it. But this is now going to inform API design for other people as it's representative of "what the big guys do." Rinse and repeat that thinking for a decade or two and everything turns into a f*cking Rube Goldberg machine for absolutely zero reason.
The "all the things" approach that AWS has taken has led to a lot of great ideas being poorly executed, leading to a mess and poor engineering.
E.g., the new (V3) of the JavaScript SDK is such a clusterf*ck I almost can't believe they had the stones to ship it.