3 ms·

> Few of us want to be making manual HTTP calls out to APIs anymore. These days a great SDK, not a great API, is a hallmark, and maybe even a necessity, of a wo

> Few of us want to be making manual HTTP calls out to APIs anymore. These days a great SDK, not a great API, is a hallmark, and maybe even a necessity, of a world class development experience. I'm of the opposite mind. A simple API that I can just call with Fetch is far better than having to learn most SDKs. Stripe's Node.js SDK is fairly clean/without headaches, but I look at stuff like the AWS JS SDK and want to gouge my eyes out. At least with an HTTP API, there's some modicum of standardization. SDKs are and will always be the wild west. The only exception with this that I see frequently is authentication. Some are simple Authorization headers w/ a Bearer <Token>, others (like PayPal the last time I implemented it) require an undocumented base64 encoding of the token.

HatchedLake721 2y ago
100%. Great API is a must have, great SDK is nice to have. In my case SDK is an unnecessary abstraction. I wrote 50+ SaaS app integrations from scratch and the last thing I want to do is bring over 50 dependencies rather than make simple HTTP requests.
MarcelOlsz 2y ago
Almost every time I use an SDK I get burned. Happened for firebase, github, and a few others. Same with ORM's.
- noitpmeder 2y ago
  In what regard? The SDKs change out from underneath you?
  - edoceo 2y ago
    Not OP but yep. Forced SDK upgrade, dependency chain and vendor driven churn. But, eg, Twilio been using the same HTTP methods for like 10 years. Many other SDK based interfaces (not necessarily Stripe) have forced that churn.
    - noitpmeder 2y ago
      Trying to understand, wouldn't you see the same issues if you depended on an API that had a breaking change? I guess my view is that shitty interfaces are shitty and people don't think enough about forwards/backwards compatibility, but it's not tied to a pure SDK or API problem
      - csomar 2y ago
        Most serious enterprises should have their API versioned.
      - MarcelOlsz 2y ago
        It adds an extra layer of maintenance. Instead of a breaking API change now you might also have an SDK that hasn't updated yet or is incompatible for any number of reasons, and you don't want to be embedded in it before you find out. It's just easier using a REST API.
  - csomar 2y ago
    SDKs are just bad because they are unnecessary. 90% of the time they'll be doing something that you should be doing; and because of that they'll be doing a bad job. I don't want an SDK that starts processes, wants to read my env variables or do some other sh*t like that. The best SDK is a REST/GraphQL endpoint. After all I am just querying the database of the service. I'd like to do it on my terms.
  - MarcelOlsz 2y ago
    It's either there isn't full coverage, or some convoluted way to migrate, or documentation is missing, or it's a 3rd party library by some guy in living in the mountains of Bhutan who happens to be on vacation at the moment, or any combination of these.
colinclerk 2y ago
I wrote the tweet that Brandur quoted... I think the bigger shifts are that developers use Checkout more, and complete more admin tasks in Stripe's Dashboard. By providing end-user UX (for both customers and backoffice), Stripe has reduced the API surface area that most developers need to consume. These changes end up having no impact on them.
hattmall 2y ago
Seriously SDKs are unnecessary bloat. Just give the basic CURL examples and let people abstract it for whatever language and implementation they want.
- halJordan 2y ago
  What this leads to are developers turning to some random unofficial github code wrapping all your pci regulated transactions
hakfoo 2y ago
The drawbacks for SDKs I see: * Needs to break the SDK containment. If you want to add some "off the menu" feature, you might be able to extend the SDK itself, butsuddenly you're running a fork that can't be maintained and updated with other dependencies. * Potential for compatibility timebombs. If you use a deprecated language feature in the SDK, or a hard-coded certificate that expires 2028-01-01, it forces a full-scale upgrade event for developers rather than fixing a single API call in their own code. In the worst case, this triggers a whole avalanche of dependency updates and breaking unrelated code. * Design impedance mismatches. Maybe you're writing procedural code and the SDK is object-oriented, or maybe it's just exposing a data structure paradigm that needs a lot of data reformatting and glue to work. A good SDK is nice to have, and if done right can be a good reference implementation for the API too. But make sure there's a usable public API under there too.
rattray 2y ago
I worked on the API and SDKs at Stripe alongside Brandur, and honestly I was a little surprised to see him say that too. I also think the underlying API has to be good for the overall DX to be good, even if these days most devs want static types and thus SDKs for any nontrivial API. (Thanks for the kind words on the Stripe Node.js SDK btw - I do hope the world can standardize more around good SDK design patterns, just as with good REST design patterns!)
uncomplexity_ 2y ago
im okay with it as long as it comes with conveniences, e.g. better type safety and better handling of errors. but yes, end of the day there will still be edge cases that should work with plain http rest apis instead of some abstraction that isn't widely adopted.
swyx 2y ago
is there somewhere we can cosign this and get the message to @pc? not taking stuff like this seriously is how Stripe starts to die. (also hi ryan, longtime, hope u are well)
- rglover 2y ago
  Hey swyx, hope you're doing well, too (shoot me an email if you see this: ryan.glover@cheatcode.co). Would love it if someone could get Patrick's attention on this. They need to move back toward the Amber Feng era of API design [1]. [1] https://amberonrails.com/building-stripes-api https://amberonrails.com/building-stripes-api
hresvelgr 2y ago
I would go even further and say SDKs shouldn't exist and API developers should ship OpenAPI 3 specs so SDKs can be generated by users. OpenAPI tooling is pretty good at the moment.
- simplesagar 2y ago
  Companies hosting their API specs publicly is a great move but I think SDKs not officially maintained and endorsed by the company always suffer from lack of upkeep which eventually makes them more of headache to use than just hitting the API directly.
rendaw 2y ago
Doesn't AWS have good reasons for its signature scheme stuff? XML is probably legacy but...
- rglover 2y ago
  My concern is with the actual JS SDK API. They shifted from a dirt-simple, chained methods API to a setup where you have to create class instances for everything (including creating config). To make it possible, they also had to shift to a naming scheme for each class that just makes the code unnecessarily clunky. E.g., it used to look like this: // This was callback-based but could have easily been wrapped with promises. s3.putObject({ option: 'blah' }, () => {}); Now it looks like this: import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; const client = new S3Client({ option: 'blah' }); const command = new PutObjectCommand({ option: 'blah' }); const response = await client.send(command); --- It's improved now, but when this first dropped for 6-12 months the docs were just TypeScript auto-generated docs that were a nightmare to decipher (and a lot of stuff didn't even have examples, so you had to guess). As for a "why this approach," it looks like they were trying to reduce the footprint of the SDK as a whole by breaking it into individual packages (smart) but instead of just keeping a simple API, they added all of this extra class instantiation and a funky client.send() pattern. The ideal would be something simple like this: import s3 from '@aws/s3'; await s3.putObject({ bucket: 'my-bucket', body: '<Some Binary>', key: 'my_file.jpg', }); Or even better: import s3 from '@aws/s3'; await s3.buckets.post({ name: 'my-bucket', region: 'us-east-2', }); await s3.objects.put({ bucket: 'my-bucket', body: '<Some Binary>', key: 'my_file.jpg', }); Why I prefer the above: it's predictable and obvious. You have a structure of <library>.<resource>.<method> which can cleanly map to HTTP methods/API endpoints. You could even (easily) have aliases for methods like s3.buckets.create() or s3.objects.upload() that just map to the canonical function.
kennu 2y ago
AWS SDKs handle some important stuff though, such as retrying database operations with backoff delays. Without it your app will fail in unexpected situations because the cloud service is designed to be stateless and return specific error codes when the client needs to retry.

HatchedLake721 2y ago

100%. Great API is a must have, great SDK is nice to have. In my case SDK is an unnecessary abstraction. I wrote 50+ SaaS app integrations from scratch and the last thing I want to do is bring over 50 dependencies rather than make simple HTTP requests.

MarcelOlsz 2y ago

Almost every time I use an SDK I get burned. Happened for firebase, github, and a few others. Same with ORM's.

noitpmeder 2y ago
In what regard? The SDKs change out from underneath you?
- edoceo 2y ago
  Not OP but yep. Forced SDK upgrade, dependency chain and vendor driven churn. But, eg, Twilio been using the same HTTP methods for like 10 years. Many other SDK based interfaces (not necessarily Stripe) have forced that churn.
  - noitpmeder 2y ago
    Trying to understand, wouldn't you see the same issues if you depended on an API that had a breaking change? I guess my view is that shitty interfaces are shitty and people don't think enough about forwards/backwards compatibility, but it's not tied to a pure SDK or API problem
    - csomar 2y ago
      Most serious enterprises should have their API versioned.
    - MarcelOlsz 2y ago
      It adds an extra layer of maintenance. Instead of a breaking API change now you might also have an SDK that hasn't updated yet or is incompatible for any number of reasons, and you don't want to be embedded in it before you find out. It's just easier using a REST API.
- csomar 2y ago
  SDKs are just bad because they are unnecessary. 90% of the time they'll be doing something that you should be doing; and because of that they'll be doing a bad job. I don't want an SDK that starts processes, wants to read my env variables or do some other sh*t like that. The best SDK is a REST/GraphQL endpoint. After all I am just querying the database of the service. I'd like to do it on my terms.
- MarcelOlsz 2y ago
  It's either there isn't full coverage, or some convoluted way to migrate, or documentation is missing, or it's a 3rd party library by some guy in living in the mountains of Bhutan who happens to be on vacation at the moment, or any combination of these.

colinclerk 2y ago

I wrote the tweet that Brandur quoted... I think the bigger shifts are that developers use Checkout more, and complete more admin tasks in Stripe's Dashboard. By providing end-user UX (for both customers and backoffice), Stripe has reduced the API surface area that most developers need to consume. These changes end up having no impact on them.

hattmall 2y ago

Seriously SDKs are unnecessary bloat. Just give the basic CURL examples and let people abstract it for whatever language and implementation they want.

halJordan 2y ago
What this leads to are developers turning to some random unofficial github code wrapping all your pci regulated transactions

hakfoo 2y ago

The drawbacks for SDKs I see: * Needs to break the SDK containment. If you want to add some "off the menu" feature, you might be able to extend the SDK itself, butsuddenly you're running a fork that can't be maintained and updated with other dependencies. * Potential for compatibility timebombs. If you use a deprecated language feature in the SDK, or a hard-coded certificate that expires 2028-01-01, it forces a full-scale upgrade event for developers rather than fixing a single API call in their own code. In the worst case, this triggers a whole avalanche of dependency updates and breaking unrelated code. * Design impedance mismatches. Maybe you're writing procedural code and the SDK is object-oriented, or maybe it's just exposing a data structure paradigm that needs a lot of data reformatting and glue to work. A good SDK is nice to have, and if done right can be a good reference implementation for the API too. But make sure there's a usable public API under there too.

rattray 2y ago

I worked on the API and SDKs at Stripe alongside Brandur, and honestly I was a little surprised to see him say that too. I also think the underlying API has to be good for the overall DX to be good, even if these days most devs want static types and thus SDKs for any nontrivial API. (Thanks for the kind words on the Stripe Node.js SDK btw - I do hope the world can standardize more around good SDK design patterns, just as with good REST design patterns!)

uncomplexity_ 2y ago

im okay with it as long as it comes with conveniences, e.g. better type safety and better handling of errors. but yes, end of the day there will still be edge cases that should work with plain http rest apis instead of some abstraction that isn't widely adopted.

swyx 2y ago

is there somewhere we can cosign this and get the message to @pc? not taking stuff like this seriously is how Stripe starts to die. (also hi ryan, longtime, hope u are well)

rglover 2y ago
Hey swyx, hope you're doing well, too (shoot me an email if you see this: ryan.glover@cheatcode.co). Would love it if someone could get Patrick's attention on this. They need to move back toward the Amber Feng era of API design [1]. [1] https://amberonrails.com/building-stripes-api https://amberonrails.com/building-stripes-api

hresvelgr 2y ago

I would go even further and say SDKs shouldn't exist and API developers should ship OpenAPI 3 specs so SDKs can be generated by users. OpenAPI tooling is pretty good at the moment.

simplesagar 2y ago
Companies hosting their API specs publicly is a great move but I think SDKs not officially maintained and endorsed by the company always suffer from lack of upkeep which eventually makes them more of headache to use than just hitting the API directly.

rendaw 2y ago

Doesn't AWS have good reasons for its signature scheme stuff? XML is probably legacy but...

rglover 2y ago
My concern is with the actual JS SDK API. They shifted from a dirt-simple, chained methods API to a setup where you have to create class instances for everything (including creating config). To make it possible, they also had to shift to a naming scheme for each class that just makes the code unnecessarily clunky. E.g., it used to look like this: // This was callback-based but could have easily been wrapped with promises. s3.putObject({ option: 'blah' }, () => {}); Now it looks like this: import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; const client = new S3Client({ option: 'blah' }); const command = new PutObjectCommand({ option: 'blah' }); const response = await client.send(command); --- It's improved now, but when this first dropped for 6-12 months the docs were just TypeScript auto-generated docs that were a nightmare to decipher (and a lot of stuff didn't even have examples, so you had to guess). As for a "why this approach," it looks like they were trying to reduce the footprint of the SDK as a whole by breaking it into individual packages (smart) but instead of just keeping a simple API, they added all of this extra class instantiation and a funky client.send() pattern. The ideal would be something simple like this: import s3 from '@aws/s3'; await s3.putObject({ bucket: 'my-bucket', body: '<Some Binary>', key: 'my_file.jpg', }); Or even better: import s3 from '@aws/s3'; await s3.buckets.post({ name: 'my-bucket', region: 'us-east-2', }); await s3.objects.put({ bucket: 'my-bucket', body: '<Some Binary>', key: 'my_file.jpg', }); Why I prefer the above: it's predictable and obvious. You have a structure of <library>.<resource>.<method> which can cleanly map to HTTP methods/API endpoints. You could even (easily) have aliases for methods like s3.buckets.create() or s3.objects.upload() that just map to the canonical function.

kennu 2y ago

AWS SDKs handle some important stuff though, such as retrying database operations with backoff delays. Without it your app will fail in unexpected situations because the cloud service is designed to be stateless and return specific error codes when the client needs to retry.