When a new API is introduced, you may want to allow developers to change its behavior without triggering a breaking change error. Mark the endpoint with the x-stability-level extension:
/api/test:
post:
x-stability-level: "alpha"
There are four levels, in increasing order of stability:
draftandalpha— can be changed freely; breaking changes are not reportedbetaandstable— breaking changes are reported as usual
Endpoints with no x-stability-level are treated like stable: any breaking change is reported.
Stability may be increased (draft → alpha → beta → stable) but never decreased. An endpoint that previously had no x-stability-level may be assigned any level.
Stability levels also control grace periods for API deprecation.