OpenAPI Spec Best Practices for API Providers

If you're building an API that other developers depend on, your OpenAPI spec is your contract. A well-maintained spec makes integration easier and reduces support burden. Here's how to do it right.

Why Your OpenAPI Spec Matters

Your spec is used for:

  • Auto-generating client SDKs
  • Documentation portals
  • Integration testing
  • Schema monitoring (like SchemaWatch)

Essential Fields

Always include these in your spec:

  • info.version — Semantic versioning (e.g., "2.1.0")
  • info.description — What your API does
  • info.contact — How to reach you
  • info.license — Usage terms

Versioning Strategy

Use semantic versioning:

  • Major (X.0.0) — Breaking changes
  • Minor (0.X.0) — New features, backwards compatible
  • Patch (0.0.X) — Bug fixes

Breaking Change Guidelines

Avoid these breaking changes when possible:

  • Removing fields
  • Changing field types
  • Making optional fields required
  • Removing endpoints

When You Must Break

If you must make breaking changes:

  1. Bump the major version
  2. Update your spec BEFORE deploying
  3. Notify users via email and changelog
  4. Give a deprecation period (30+ days)
  5. Document migration steps

Validate Your Spec

Use our free OpenAPI validator to check your spec before publishing. It catches common issues and ensures compatibility with monitoring tools.

Help Your Users Monitor

Encourage your users to use schema monitoring tools. When they catch changes early, they're less likely to file support tickets when things break.