Skip to content
releo

Learn

Guides to API change management

Breaking changes, versioning, deprecation, migrations and verification: practical guides for teams that publish APIs and teams that depend on them.

7 min read

What is an API breaking change?

An API breaking change forces existing clients to change their code. See 12 common examples, why tests miss them, and how to detect and verify them before release.

Read guide →

6 min read

API versioning strategies, compared

Compare URL, header, query and date-based API versioning, see how Stripe and GitHub version their APIs, and learn what versioning does not solve.

Read guide →

7 min read

How to deprecate an API

API deprecation guide: Deprecation (RFC 9745) and Sunset (RFC 8594) headers, notice periods, brownouts, 410 Gone, and getting consumers migrated.

Read guide →

6 min read

OpenAPI diff: detecting breaking changes in CI

Use an OpenAPI diff in CI to catch breaking API changes before merge. Compare oasdiff and openapi-diff, with a GitHub Actions example.

Read guide →

7 min read

How to migrate to a new API version safely

Step-by-step API migration guide: inventory call sites, map breaking changes, verify behavior with real traffic, and roll out gradually.

Read guide →

6 min read

Traffic replay testing, explained

Traffic replay testing re-sends real requests to old and new versions of a service and compares responses. How it works, handling noise, and safety.

Read guide →

8 min read

API testing: types, tools and a strategy that works

API testing explained: unit, contract, integration, end-to-end, load, security and replay tests, the tool categories for each, and a layered strategy.

Read guide →

8 min read

REST vs GraphQL vs gRPC: which API style to choose

REST vs GraphQL vs gRPC compared: data fetching, performance, tooling, caching, and how each API style handles change, versioning and deprecation.

Read guide →

8 min read

API design best practices

API design best practices for naming, resources, errors, pagination, idempotency, versioning and evolvability, with examples you can apply to REST APIs.

Read guide →

8 min read

API security best practices

API security best practices: authentication, authorization, OAuth 2.0, API keys, rate limiting, input validation, logging, and the OWASP API Security Top 10.

Read guide →

7 min read

How to write great API documentation

How to write API documentation: reference vs guides, OpenAPI, working examples, quickstarts, changelogs and deprecation notices developers can act on.

Read guide →

API glossary

All terms →

Coming soon

Ship API changes without breaking your customers.

Releo is in private beta. Join the waitlist for early access.