Subscription states

State transition diagram

Explanation

When creating a subscription, the subscriber needs to specify the requested state in its request. This state, however, is never persisted. Instead, the request is immediately evaluated for correctness and endpoint health.

• If everything is in order, the corresponding subscription will be created in the active state.
• Otherwise the server will return an error indication and no subscription will be created.

To unsubscribe, the client can either send an HTTP DELETE request for the subscription or update the subscription's state to off using a POST request. In the resulting off state, the server server no longer collects notification events. Reactivating such a subscription would be problematic, since it would result in the client missing data for the period during which the subscription was inactive.

To avoid the false impression of a continuously operational subscription, reactivation of subscriptions in the off state is not allowed. Instead, the subscriber can create a new subscription with identical criteria, which ensures that the operational lifetime of each subscription is clear and explicit.

Whenever resources are created or updated to match the criteria of an active subscription, the server attempts to POST a notification to the endpoint URL specified in the subscription. If this notification attempt fails for any reason, the subscription is moved to the error state, where the server attempts a few more retries before giving up. From this state, three possible transitions can occur:

• If a retry is succesful, the subscription is automatically moved back to the active state.
• The client can also initiate a recovery process to move the subscription back to the active state, as described in a later section.
• If the client leaves the subscription in the error state for an extended amount of time (approximately a month), then the server moves the subscription to the off state and recovery is no longer possible.