Current version of the spec defines epoch as:
Epoch: Description: The Discovery Endpoint's epoch value for this Service Entry. This specification does not mandate any particular semantic meaning to the value used. For example, implementations are free to use a value that represents a timestamp or could choose to simply use a monotonically increasing number. The only requirement is that the value MUST always increase each time the Service Entry is updated. This allows for a quick integer comparision to determine which version of this Service Entry is the latest - meaning, the one with the larger integer value.
For the purposes of this example, epoch starts at 1 and increases by one each time.
In the following table -
indicates no epoch value was supplied (Req E) or that no record exists (Rec E) and abreviations Req
is Request
, Rec
is Record
, and E
is Epoch
.
Action | Req E | Rec E | Current | Proposal #1 | Proposal #2 |
---|---|---|---|---|---|
POST /services/ |
- | - | 1 (generated) | 1 (generated) | 1 (generated) |
POST /services/ |
- | 1 | 2 (generated) | 2 (generated) | 2 (generated) |
POST /services/ |
2 | - | 2 (incoming) | 2 (incoming) | 2 (incoming) |
POST /services/ |
2 | 1 | 2 (incoming) | 2 (incoming) | 2 (incoming) |
POST /services/ |
2 | 2 | 409 error | 2 (incoming) | 409 error |
POST /services/ |
2 | 3 | 409 error | 2 (incoming) | 409 error |
- | |||||
PUT /services/{id} |
- | - | 1 (generated) | 1 (generated) | 1 (generated) |
PUT /services/{id} |
- | 1 | 2 (generated) | 2 (generated) | 2 (generated) |
PUT /services/{id} |
2 | - | 2 (incoming) | 409 error | 2 (incoming) |
PUT /services/{id} |
2 | 1 | 2 (incoming) | 409 error | 2 (incoming) |
PUT /services/{id} |
2 | 2 | 409 error | 3 (generated) | 409 error |
PUT /services/{id} |
2 | 3 | 409 error | 409 error | 409 error |
- | |||||
DELETE /services[/{id}] |
- | - | 404 error | 404 error | 200 |
DELETE /services[/{id}] |
- | 1 | 200 deleted | 200 deleted | 200 deleted |
DELETE /services[/{id}] |
2 | - | 404 error | 404 error | 200 |
DELETE /services[/{id}] |
2 | 1 | 200 deleted | 409 error | 200 deleted |
DELETE /services[/{id}] |
2 | 2 | 200 deleted | 200 deleted | 409 error |
DELETE /services[/{id}] |
2 | 3 | 409 error | 409 error | 409 error |
TL;DR: are supplied epoch values "the target epoch to assign the record", "a constraint of the epoch the record must have to accept the change", or the first for POST and the latter for PUT and DELETE?
Current : epoch is the version to assign the next state of the record, except applied inconsistently to equal epochs (an unintended bug)
Proposal 1: epoch is the version to assign the next state of the record for POST and a version constraint indicating whether to make the update for PUT and DELETE
Proposal 2: epoch is the version to assign the next state of the record (also make DELETE idempotent)