A few irks:
- 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',
}).promise().then((response) => {
// Handle URL here.
});
---
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.