Bloom blog
Writing on OpenAPI, SDKs, and the developer experience.
Posts from the Bloom team on docs migration, SDK generation, API release readiness, and the workflow API teams need from one OpenAPI spec.
-
Publishing a TypeScript SDK to npm in 2026
A practical guide to publishing a TypeScript SDK on npm — package.json shape, exports map, dual ESM/CJS, semver discipline, .npmignore, 2FA, and dry-run.
-
OpenAPI validator: 5 tools tested in 2026
Five OpenAPI validators compared on real specs: Spectral, Redocly CLI, openapi-cli, swagger-cli, and Bloom. What to ship in CI.
-
OpenAPI to npm package: a publishing workflow
End-to-end workflow: OpenAPI spec → generated TypeScript SDK → versioned npm package → docs site. CI pipeline patterns, dry-run releases, and provenance.
-
Migrating from Stainless to Bloom without losing the SDK experience
What changes (and what doesn't) when you move your OpenAPI workflow off Stainless. A practical walkthrough using the files you already own.
-
Generate a TypeScript SDK from OpenAPI: end-to-end in 2026
A practical guide to generating a TypeScript SDK from an OpenAPI spec — spec hygiene, picking a generator, package shape, examples, and publishing. With concrete commands.
-
Generate a Python SDK from OpenAPI: end-to-end in 2026
Generate a Python SDK from OpenAPI: spec hygiene, generator choices, packaging, async support, and a practical PyPI workflow.
-
DX tools every API company needs in 2026
The DX toolchain for API companies — docs, SDKs, examples, sandbox, status, observability, and agent-readable surfaces — with concrete picks at each tier of growth.
-
The developer-experience toolkit for API startups in 2026
What API startups need in DX: docs, SDKs, examples, status, support, telemetry, and one OpenAPI workflow without enterprise pricing.
-
Detecting breaking changes in OpenAPI: a 2026 guide
What counts as a breaking change in OpenAPI vs in the generated SDK — concrete rules, the tools that catch them (oasdiff, openapi-diff, Bloom), and how to wire detection into CI.
-
The API launch checklist (with templates)
A practical pre-launch checklist for a public API in 2026: spec hygiene, SDKs, docs, examples, status page, changelog, rate limits, auth, support, and what to monitor on day one.
-
Generate an SDK from OpenAPI in five minutes
Upload an OpenAPI 3.x spec, get a typed TypeScript and Python SDK preview with a runnable example. Step-by-step, with what's in the output.
-
Stainless is joining Anthropic. What it means for your SDK and docs
What changes (and what doesn't) for Stainless customers after the Anthropic acquisition. The questions to ask, the files to inventory, and what a reversible migration looks like.
-
How to evaluate API documentation tools without getting locked in
A practical buyer's lens for picking API docs tooling: OpenAPI fidelity, SDK examples, llms.txt, migration risk, and pricing transparency. The criteria buyers actually use.
-
OpenAPI vs stainless.yml: what each file actually controls
OpenAPI defines the API. stainless.yml defines the SDK. Most migration confusion comes from mixing the two. A field-by-field walkthrough.
-
llms.txt: the quietest SEO win for API docs in 2026
What llms.txt is, why agent-readable docs matter for API teams, and how to ship it from an OpenAPI spec without rewriting your docs site.
-
SDK compatibility reports: the diff that makes migrations reversible
What's in a generated-SDK compatibility report, why teams skip it, and how to read one when the stakes are a published package.
-
Swagger vs OpenAPI: what changed, what didn't, and what to use in 2026
Swagger and OpenAPI mean different things in practice. A short guide to the names, the actual specification, and what your team should standardize on today.
-
Examples of great API documentation (and what to copy from them)
Six docs sites worth studying — Stripe, Twilio, Linear, GitHub, Plaid, Anthropic — with the specific design choices that make each one work.
-
REST API versioning best practices for teams shipping SDKs
Versioning strategies that actually work in 2026 — URL path, header, query, content negotiation. With trade-offs and what to pick for a public API.
-
OpenAPI best practices for SDK-friendly specs
The OpenAPI patterns that produce idiomatic SDK code — naming, schema reuse, examples, security. Practical, with what to do and what to avoid.
-
OpenAPI 3.1 vs 3.0: what's new and what to use in 2026
The differences between OpenAPI 3.0 and 3.1 that actually matter — JSON Schema 2020-12, webhooks, nullable, examples. Plus how to upgrade safely.
-
REST vs GraphQL: which one do you need in 2026?
A practical guide to choosing between REST and GraphQL for a new API in 2026. Where each one shines, where each one bites, and what to pick for typical SaaS use cases.
-
Swagger Codegen vs modern SDK generators: what changed, what to use
Swagger Codegen and OpenAPI Generator built the SDK-from-spec category. Where they still fit, where modern alternatives win, and a practical decision tree for 2026.
-
OpenAPI security best practices for production APIs
How to model auth, secrets, scopes, and audit-friendly behavior in OpenAPI 3.x. Practical patterns for API keys, OAuth, mTLS, and the gotchas that bite in production.
-
OpenAPI webhooks: the right pattern in 3.1
How to model webhooks in OpenAPI 3.1, why the 3.0 callbacks workaround was awkward, and what generated SDKs and docs should do with webhook definitions.
-
What is an MCP server? A practical introduction
MCP (Model Context Protocol) lets AI agents call your API as a typed tool. What an MCP server is, what it isn't, and how to think about shipping one for your product.
-
MCP server security: what to lock down before shipping
MCP servers expose tools to AI agents. Auth, sandboxing, rate limits, audit logs — the security checklist before exposing internal capabilities to an LLM client.
-
Generate an MCP server from OpenAPI: what's possible in 2026
OpenAPI 3.x specs can drive MCP server generation. What translates cleanly, what needs human input, and the tools shipping OpenAPI-to-MCP today.
-
OpenAPI codegen: what it does, which tool to pick, what to avoid
OpenAPI codegen turns specs into SDKs in 50+ languages. Where each tool wins, what makes generated code idiomatic, and the patterns that hurt downstream.