> 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.<p>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.<p>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.
> The new API is trying to move away from a model where subobjects in an API resource are expanded by default, to one where they need to be requested with an include parameter. We had plenty of discussions about this before I left.<p>This feels like the worst middleground between REST and GraphQL. All of the data flexibility of GraphQL with the static schemas of REST. Wasn't this kind of thing the whole idea underpinning GraphQL?<p>Maybe you can get around this with new SDK generators handling type safety for you, but I am definitely not looking forward to trying to understand the incomprehensible 5 layers of nested generics needed to make that work.<p>I remember looking up to Stripe as pioneers of developer experience. This reads like a PM with their back against the wall with a mandate from above (make requests n% faster) rather than a developer-first design choice made to help people build better systems.
> These days a great SDK, not a great API, is a hallmark, and maybe even a necessity, of a world class development experience.<p>IMO, you can't build a great SDK without a great API. Duct tape only goes so far.
> There was a time not too long ago when Stripe cutting a new API version would’ve been a major event in the tech world, but in three months I didn’t come across a single person who mentioned it.<p>I don't think it would have been a major event, ever. Few people care about a API version bump in the abstract. It'll mostly be big news if it's bad news somehow (user-visible feature regressions, access restrictions, etc) or if there's some <i>significant</i> new features.<p>This appears to be neither. It's just inconsequential re-arranging of the living room furniture for better feng shui.
>That’s got to be true too. 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.<p>I may be in that "few of us" set because I really prefer a simple HTTP API that I can implement myself rather than having to take a library dependency on some code with transitive dependencies and unknown future maintainership. A good SDK is nice to have but a integrating with a bad one by accident is horrible.
There are a couple of changes more that arguably made the API worse:<p>* Event payloads changed to be “thin events”<p>* List endpoints became only eventually consistent<p>They also took away the “expand” parameter, which seems more useful that the new “include” one that works in some endpoints.<p>Generally their API design seems much more confusing and inconsistent nowadays. But to be fair their API is much bigger too. I guess it is hard to keep the same quality when you have so many engineers working on it.
Strange that <a href="https://jsonapi.org/examples/" rel="nofollow">https://jsonapi.org/examples/</a> never went into the masses, I suspect because it came out around the same time as GraphQL.<p>For me it’s the perfect mix between doing REST from scratch and GraphQL.<p>And it comes with the similar include and expand pattern that Stripe v2 introduced.
I feel that with typescript you can sort of build an SDK by creating a thin wrapper around fetch and have it consume the API types as a generic.<p>This way you still have the benefits of type safety without the bloat of creating an actual SDK.<p>SDKs tend to be useful when they hold state / don’t just proxy to a rest call, but I don’t see why we need wrapper libraries. They also hide away the complexity of knowing how the rest api is meant to consume data (query / params / body / encoding). So the assumption is the rest API itself makes sense.<p>I took this approach with a backend typescript framework called vramework.dev which can generate openapi specs as well as the thin fetch wrapper, and feel like for my projects satisfies my needs.
If you use APIs make sure you don’t break them: <a href="https://github.com/Tufin/oasdiff">https://github.com/Tufin/oasdiff</a>
> a new API version also presents an opportunity to clear out blemishes, and I expected to see more of that<p>Curious, what are some other Stripe API blemishes that folks would have liked to see cleaned up in a v2?
Reminiscent of the changes to the Microsoft Graph API, which personally I wasn't a fan of. Hope stripe can maintain its developer first mentality.