Skip SDKs in Simple Integrations

When building software, we often find ourselves at a crossroads: to use a third-party SDK or to interact directly with HTTP-based APIs. Recently, I shared my preference for the latter on 𝕏, and it sparked quite a conversation. So, I want to dive into why, in certain cases, avoiding SDKs can be beneficial and simplify your development process.

The Drawbacks of SDKs

Mental Model Mismatch

One of my main gripes with SDKs is the mental model they impose. They often organize interactions with an API in a way that's different from how I would naturally approach the problem. I prefer the simplicity of calling a function, getting the results, caching them, and parsing the response as needed. It's transparent and straightforward. With SDKs, you're dealing with a black box, which can obscure the integration point between your code and the external servers.

Technically once you call the HTTP endpoint you've entered black box territory, but by using an SDK you're having that black box extend from the service's servers onto your own and I would prefer to not do that if I don't have to.

Hidden Complexities

SDKs can hide complexities that only surface when you delve into the documentation. They might rely on global state or other behind-the-scenes mechanisms that aren't immediately apparent. Often they reference global environment variables that you have to look up in the documentation to understand as well. This lack of transparency can lead to confusion and unexpected behaviors in your application.

Outdated Dependencies

Another issue is that SDKs sometimes rely on outdated dependencies, which can conflict with your project's existing libraries. They may also introduce global state that evolves over time, adding to the maintenance burden. And if the SDK isn't designed for your specific environment, you're in for a world of confusion.

Learning Overhead

Using an SDK means you have to learn not just the API for the server but also the API for the SDK itself. This adds an unnecessary learning curve and can slow down development, especially when you're dealing with a simple integration.

The Benefits of Direct API Calls

Offline Development

I'm a big proponent of being able to develop applications offline. It speeds up the development process, simplifies testing, and allows you to simulate various conditions without complex test infrastructure. By using tools like MSW (mock service worker), I can easily mock the APIs I'm calling, which is much more straightforward than figuring out how to mock the calls made by an SDK.

Typing Information

Some argue that SDKs provide valuable typing information. However, I find it quite easy to look up the REST endpoint's response and create my own types using tools like Zod. This approach has not posed any significant challenges for me in simple cases.

Swappability

It's often easier to swap vendors when you are hitting HTTP endpoints directly than when you're dealing with a full blown SDK in large part because of the problems described. HTTP endpoints you hit yourself are easier to follow as you're going through the current code and migrating it over to the new provider. If you're using an SDK, there are things which are happening that may be important, but are totally obscured from your view.

When to Use SDKs

Despite my reservations, I acknowledge that SDKs have their place. If you're doing a deep integration with a service, where you need to interact with many endpoints, an SDK can be incredibly helpful. In my current SaaS project, I'm only dealing with a couple of endpoints for Twilio and Stripe, so my integration files are quite lean. But for more complex integrations, I wouldn't hesitate to use an SDK (ok, maybe I would hesitate for a bit, but not for long, I'm an adult).

Conclusion

SDKs are powerful tools, and I'm glad they exist. However, for simple API integrations, they can introduce unnecessary bloat and cognitive overhead. By interacting directly with HTTP endpoints, you can keep your codebase lean and your development process agile. Remember, not everything in software has to be dogma and there's judgement involved. I hope my perspective helps you make informed decisions in your own projects. Have a great day coding!