https://trybloom.so/blog/ Posts from the Bloom team on OpenAPI, SDKs, API docs, and migrations. en-us Mon, 25 May 2026 00:00:00 GMT https://trybloom.so/blog/publish-typescript-sdk-to-npm/ https://trybloom.so/blog/publish-typescript-sdk-to-npm/ Mon, 25 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/openapi-validator/ https://trybloom.so/blog/openapi-validator/ Mon, 25 May 2026 00:00:00 GMT Five OpenAPI validators compared on real specs: Spectral, Redocly CLI, openapi-cli, swagger-cli, and Bloom. What to ship in CI. https://trybloom.so/blog/openapi-to-npm-package/ https://trybloom.so/blog/openapi-to-npm-package/ Mon, 25 May 2026 00:00:00 GMT End-to-end workflow: OpenAPI spec → generated TypeScript SDK → versioned npm package → docs site. CI pipeline patterns, dry-run releases, and provenance. https://trybloom.so/blog/migrating-from-stainless-to-bloom/ https://trybloom.so/blog/migrating-from-stainless-to-bloom/ Mon, 25 May 2026 00:00:00 GMT What changes (and what doesn't) when you move your OpenAPI workflow off Stainless. A practical walkthrough using the files you already own. https://trybloom.so/blog/generate-typescript-sdk-from-openapi/ https://trybloom.so/blog/generate-typescript-sdk-from-openapi/ Mon, 25 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/generate-python-sdk-from-openapi/ https://trybloom.so/blog/generate-python-sdk-from-openapi/ Mon, 25 May 2026 00:00:00 GMT Generate a Python SDK from OpenAPI: spec hygiene, generator choices, packaging, async support, and a practical PyPI workflow. https://trybloom.so/blog/dx-tools-for-api-companies/ https://trybloom.so/blog/dx-tools-for-api-companies/ Mon, 25 May 2026 00:00:00 GMT The DX toolchain for API companies — docs, SDKs, examples, sandbox, status, observability, and agent-readable surfaces — with concrete picks at each tier of growth. https://trybloom.so/blog/developer-experience-tools/ https://trybloom.so/blog/developer-experience-tools/ Mon, 25 May 2026 00:00:00 GMT What API startups need in DX: docs, SDKs, examples, status, support, telemetry, and one OpenAPI workflow without enterprise pricing. https://trybloom.so/blog/breaking-changes-openapi/ https://trybloom.so/blog/breaking-changes-openapi/ Mon, 25 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/api-launch-checklist/ https://trybloom.so/blog/api-launch-checklist/ Mon, 25 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/generate-sdk-from-openapi-in-five-minutes/ https://trybloom.so/blog/generate-sdk-from-openapi-in-five-minutes/ Sun, 24 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/stainless-joining-anthropic-what-it-means/ https://trybloom.so/blog/stainless-joining-anthropic-what-it-means/ Sat, 23 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/how-to-evaluate-api-documentation-tools/ https://trybloom.so/blog/how-to-evaluate-api-documentation-tools/ Fri, 22 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/openapi-vs-stainless-yml-what-each-actually-controls/ https://trybloom.so/blog/openapi-vs-stainless-yml-what-each-actually-controls/ Thu, 21 May 2026 00:00:00 GMT OpenAPI defines the API. stainless.yml defines the SDK. Most migration confusion comes from mixing the two. A field-by-field walkthrough. https://trybloom.so/blog/llms-txt-the-quietest-seo-win-for-api-docs/ https://trybloom.so/blog/llms-txt-the-quietest-seo-win-for-api-docs/ Wed, 20 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/sdk-compatibility-reports-explained/ https://trybloom.so/blog/sdk-compatibility-reports-explained/ Tue, 19 May 2026 00:00:00 GMT What's in a generated-SDK compatibility report, why teams skip it, and how to read one when the stakes are a published package. https://trybloom.so/blog/swagger-vs-openapi-in-2026/ https://trybloom.so/blog/swagger-vs-openapi-in-2026/ Mon, 18 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/examples-of-great-api-documentation/ https://trybloom.so/blog/examples-of-great-api-documentation/ Sun, 17 May 2026 00:00:00 GMT Six docs sites worth studying — Stripe, Twilio, Linear, GitHub, Plaid, Anthropic — with the specific design choices that make each one work. https://trybloom.so/blog/rest-api-versioning-best-practices/ https://trybloom.so/blog/rest-api-versioning-best-practices/ Sat, 16 May 2026 00:00:00 GMT Versioning strategies that actually work in 2026 — URL path, header, query, content negotiation. With trade-offs and what to pick for a public API. https://trybloom.so/blog/openapi-best-practices-for-sdk-friendly-specs/ https://trybloom.so/blog/openapi-best-practices-for-sdk-friendly-specs/ Fri, 15 May 2026 00:00:00 GMT The OpenAPI patterns that produce idiomatic SDK code — naming, schema reuse, examples, security. Practical, with what to do and what to avoid. https://trybloom.so/blog/openapi-3-1-vs-3-0-what-to-use/ https://trybloom.so/blog/openapi-3-1-vs-3-0-what-to-use/ Thu, 14 May 2026 00:00:00 GMT The differences between OpenAPI 3.0 and 3.1 that actually matter — JSON Schema 2020-12, webhooks, nullable, examples. Plus how to upgrade safely. https://trybloom.so/blog/rest-vs-graphql-which-do-you-need-in-2026/ https://trybloom.so/blog/rest-vs-graphql-which-do-you-need-in-2026/ Wed, 13 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/swagger-codegen-vs-modern-sdk-generators/ https://trybloom.so/blog/swagger-codegen-vs-modern-sdk-generators/ Tue, 12 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/openapi-security-best-practices/ https://trybloom.so/blog/openapi-security-best-practices/ Mon, 11 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/openapi-webhooks-pattern/ https://trybloom.so/blog/openapi-webhooks-pattern/ Sun, 10 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/what-is-mcp-server/ https://trybloom.so/blog/what-is-mcp-server/ Sat, 09 May 2026 00:00:00 GMT 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. https://trybloom.so/blog/mcp-server-security/ https://trybloom.so/blog/mcp-server-security/ Fri, 08 May 2026 00:00:00 GMT MCP servers expose tools to AI agents. Auth, sandboxing, rate limits, audit logs — the security checklist before exposing internal capabilities to an LLM client. https://trybloom.so/blog/openapi-to-mcp-server/ https://trybloom.so/blog/openapi-to-mcp-server/ Thu, 07 May 2026 00:00:00 GMT OpenAPI 3.x specs can drive MCP server generation. What translates cleanly, what needs human input, and the tools shipping OpenAPI-to-MCP today. https://trybloom.so/blog/openapi-codegen-explained/ https://trybloom.so/blog/openapi-codegen-explained/ Wed, 06 May 2026 00:00:00 GMT OpenAPI codegen turns specs into SDKs in 50+ languages. Where each tool wins, what makes generated code idiomatic, and the patterns that hurt downstream.