This pattern involves replacing boolean flags, typically used to represent state changes in resources, with timestamps in API responses. This approach provides more granular information about when a resource’s state was last changed, enhancing traceability and auditability.

Details

In traditional API design, boolean flags are often used to indicate the status of a resource, such as isActive, isDeleted, or isUpdated. However, these flags only provide a binary state without any context regarding when the state change occurred. By using timestamps such as activatedAt, deletedAt, or updatedAt, APIs can convey not only the current state but also the exact time the state was last modified.

This method increases the transparency of data changes over time and can be particularly useful in debugging, auditing, and synchronizing data across distributed systems. It helps clients make more informed decisions based on the age of the data.

Common Pattern Names/Synonyms

  • Timestamp-based State Management
  • Temporal State Indicators
  • Date-flagged Status Management

Common Use Cases

  1. Audit and Compliance: When businesses need to provide a history of state changes for compliance and auditing purposes.
  2. Data Synchronization: In distributed systems where multiple clients or services might modify a resource, timestamps help resolve conflicts and determine the latest version.
  3. Caching Strategies: Clients can use timestamps to decide whether to fetch new data from the server or use cached data.
  4. Debugging and Monitoring: Developers can track when changes occur, which is useful for diagnosing issues in dynamic environments.

Mermaid Sequence Diagrams

Below is a Mermaid sequence diagram illustrating a typical interaction pattern using timestamps instead of boolean flags:

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: GET /resource/123
    Server->>Client: 200 OK { "id": 123, "updatedAt": "2023-10-13T12:00:00Z" }
    Note over Client,Server: Client checks if update is needed based on timestamp
    Client->>Server: PUT /resource/123 { "data": "New Data", "lastKnownUpdate": "2023-10-13T12:00:00Z" }
    Server->>Client: 200 OK { "updatedAt": "2023-10-13T14:00:00Z" }

Examples

Example 1: API Response using Timestamps instead of Boolean Flags

{
  "userId": 101,
  "username": "john_doe",
  "isActive": true,         // traditional boolean flag
  "deletedAt": null,        // using timestamp to indicate non-deletion
  "activatedAt": "2023-09-01T08:00:00Z"
}

Explanation: Instead of simply indicating that isActive is true, activatedAt provides the exact time when the user account was activated. deletedAt being null indicates that the user account has not been deleted.

Example 2: Handling Updates with Timestamps

  • Client retrieves a resource.
  • Client updates the resource only if their last known updatedAt matches the server’s current updatedAt, effectively using the timestamp to manage concurrency and ensure data integrity.

Example 3: Conditional GET Request

  • A client can perform a conditional GET request using the If-Modified-Since header, passing the timestamp of the last known update.
  • The server checks the timestamp and decides whether to return a full response or a 304 Not Modified.

Example 4: Tracking Resource Deletion with Timestamps

{
  "userId": 102,
  "username": "jane_smith",
  "deletedAt": "2023-10-12T15:00:00Z"  // timestamp indicates when the resource was deleted
}

Explanation: Instead of using a boolean isDeleted flag, deletedAt provides a precise timestamp of when the user account was marked as deleted. If deletedAt is not null, it indicates that the resource is no longer active.

Updated: