API Client Libraries and SDKs

Three ways to call an API

You can talk to an API at three levels of abstraction. Raw HTTP gives total control and no extra dependency, but you write everything — serialisation, error handling, retries — yourself. A generated client is produced from an API specification, giving typed methods that track the spec. A hand-written SDK is a crafted library offering a polished, idiomatic interface.

None is universally best. The right choice depends on how much the convenience is worth to you, how much control you need, and how comfortable you are taking on a dependency. The trade-off is fundamentally between doing the work yourself and trusting someone else's code to do it for you.

Convenience versus control

An SDK can save real effort: authentication, retries, pagination and serialisation handled for you, often with types that catch mistakes early. For a well-maintained library this is a genuine head start.

• Pros — less boilerplate, fewer bugs in solved problems, faster to working code.
• Cons — a dependency to track, less control over behaviour, and the SDK's bugs become yours.

Raw HTTP is the opposite: more work, but complete control and nothing to update. The decision often hinges on how standard your needs are. For ordinary usage an SDK usually wins; for unusual requirements or a desire to minimise dependencies, raw HTTP can be the cleaner path.

Evaluating an SDK

Before adopting any client library, weigh it like the long-term dependency it is. A poorly maintained SDK can cost more than the code it saves.

Check that it is actively maintained, with recent releases and responsive handling of issues. Confirm it tracks the API's current version and supports the runtime you use. Look at how it handles the things you care about — does it expose retry and timeout configuration, or hide them? Read enough of its source to gauge quality, since you are inheriting it. An unmaintained library wrapping an evolving API will eventually drift out of date and become your problem to fix or replace.

Wrap what you adopt

Whichever you choose, insulate your application from it behind a thin wrapper of your own. Your code calls your interface; the wrapper translates to the SDK or raw HTTP underneath.

class AccountClient:
    def get(self, id):
        # delegates to SDK or raw HTTP
        return self._impl.fetch(id)

This isolation pays off repeatedly: you can swap the SDK for raw HTTP (or vice versa) without touching the rest of the app, add your own resilience and logging in one place, and keep external types from leaking everywhere. It is a small upfront cost that buys lasting flexibility. Start integration design at the developer portal.