Managing the API lifecycle
An API is not static: over its life it moves from a draft to a live API, and eventually towards retirement. Daikoku models this with an API state, and drives the consequences for consumers and their API keys automatically.
The API states
| State | In the catalog | Subscribable | Existing keys |
|---|---|---|---|
| Created (draft) | Hidden | No | — |
| Published | Listed | Yes | Working |
| Deprecated | Listed | Yes, with a warning | Working |
| Blocked | Hidden (401) | No | Cut |
State changes are guarded: only sound transitions are allowed. For example, you cannot send a published API that already has subscriptions back to draft, and you cannot jump straight from draft to blocked.
Changing the state
Open the API in its backoffice, change its state and save. The available transitions depend on the current state; an invalid transition is refused with a conflict error.
Going back to draft is refused once an API has subscriptions — consumers already depend on it.
Deprecating an API
Deprecating tells consumers the API is on its way out without breaking anything:
- it stays in the catalog and existing API keys keep working;
- it is still subscribable, but a consumer is asked to confirm before subscribing to a deprecated API;
- teams that already subscribed receive a deprecation notification (and an email) so they can plan their migration.
Deprecation is reversible: you can publish the API again.
Blocking an API
Blocking is the hard stop. When you block an API:
- it disappears from the catalog and its page returns
401; - new subscriptions are refused;
- every API key derived from its subscriptions is cut — the keys are disabled on the Otoroshi side, but the subscriptions themselves are kept;
- the impacted consumer teams are notified by notification and email.
Because nothing is deleted, blocking is fully reversible: moving the API back to published or deprecated re-enables the keys and restores access.
If several APIs share a keyring (aggregated keys), blocking one API only removes its subscriptions' rights from the shared key. The other APIs keep working.
Blocking a single subscription
You do not have to block the whole API to cut off one consumer. From the API's subscriptions view, a producer can block (or re-enable) an individual subscription. This:
- removes only that subscription's rights from its shared key, leaving the other subscriptions untouched;
- is reserved to editors of the producing team;
- is preserved across an API block/deblock cycle — if you block then unblock the whole API, a subscription you had blocked by hand stays blocked until you re-enable it explicitly.