Matchup
No SDK (raw HTTP) vs hand-written SDK
Many APIs start with docs and curl examples and nothing else. This matchup shows what callers give up without an SDK, and what you take on when you write one, with maintenance counted double.
Verdict
Hand-written SDK wins, 9 to 2, over No SDK (raw HTTP).
No SDK (raw HTTP) 2/21 Hand-written SDK 9/21
No SDK (raw HTTP) takes maintenance. Hand-written SDK takes typing, auth handling, retries, pagination and error handling.
| Criterion | No SDK (raw HTTP) | Hand-written SDK |
|---|---|---|
| TypingEdge: Hand-written SDK | Weak No types. Callers parse JSON into maps or write their own models, and nothing tells them when the API changes. | Solid Types can be as idiomatic as the authors make them, but they are written by hand and can drift from the API as it changes. |
| Auth handlingEdge: Hand-written SDK | Weak Every caller sets headers, signs requests and refreshes tokens by hand. | Strong Full control: any flow, including OAuth token refresh and custom signing, can be built exactly as the API needs it. |
| RetriesEdge: Hand-written SDK | Weak Only if each caller writes a retry loop or configures their HTTP library. | Partial Retries exist only if someone built them, language by language. Check each SDK's source; behaviour often differs between languages. |
| PaginationEdge: Hand-written SDK | Weak Every caller writes the paging loop, and many stop at the first page. | Partial Paging helpers are possible and often nice, but each one is written by hand for each language and each list endpoint. |
| Error handlingEdge: Hand-written SDK | Weak Callers check status codes and parse error bodies themselves. | Solid Error types can be designed with care, but keeping them in step with every documented error response is manual work. |
| Maintenance×2Edge: No SDK (raw HTTP) | Partial Nothing for you to maintain, but every change to the API is work for every caller, and you cannot see who breaks. | Weak Every new endpoint, field and deprecation is hand work in every language, and the SDKs drift from the API when that work slips. |
The verdict, and when to ignore it
Hand-written SDK wins, 9 to 2, over No SDK (raw HTTP). No SDK (raw HTTP) takes maintenance. Hand-written SDK takes typing, auth handling, retries, pagination and error handling.
Pick No SDK (raw HTTP) when
Your API is small and stable, your callers are few and technical, and you'd rather spend the time on good docs and an accurate OpenAPI description.
Pick Hand-written SDK when
Callers struggle with auth or paging, support tickets repeat the same integration mistakes, and you can staff the SDK for the long run.
More matchups
Hand-written SDK vs OpenAPI Generator
OpenAPI Generator wins, 10 to 8, narrowly, over Hand-written SDK.
OpenAPI Generator vs Microsoft Kiota
Microsoft Kiota wins, 17 to 13, narrowly, over OpenAPI Generator.
Hand-written SDK vs MCP server
Too close to call: Hand-written SDK 10, MCP server over your API 9.
Speakeasy vs OpenAPI Generator
Speakeasy wins, 15 to 10, over OpenAPI Generator.