Idempotency

The examples below illustrate how idempotency works best.

Example 1: Two requests, connectivity lost

Situation:

  • T0: Google sends a capture request to the integrator with request ID ABC123.
  • T1: The integrator server receives this request and processes it successfully.
  • T2: Google's server loses power prior to receiving the response in T1.
  • T3: Google's server power is restored and the same capture request (ID ABC123) is sent with all the same parameters to the integrator's server (except for requestTimestamp).

Outcome:

In this case the integrator server must reply with the same reply given at T1. since all the parameters except for responseTimestamp) are the same. The user is only debited once, at T0. T3 has no monetary impact to the user.

Example 2: Two requests, first request during maintenance

Situation:

  • T0: Integrator server's database is down for maintenance.
  • T1: Google sends a request to the integrator with request ID ABC124.
  • T2: Integrator correctly returns UNAVAILABLE status code.
  • T3: Google's server receives response. Schedules a retry.
  • T4: Integrator server's database is back online.
  • T5: Google sends same request from T1 (except for new requestTimestamp).
  • T6: Integrator server receives request and returns an OK status code along with full response.

Outcome:

In this case the integrator server must process the request in T6 and not return HTTP 503 (UNAVAILABLE). Instead, the integrator server should fully process the request and return OK with appropriate messaging. Note that while the system is UNAVAILABLE Google may make repeated requests similar to T1. Each request should result in a message similar to T2. Eventually T5 and T6 will occur.

Example 3: Two requests, Google error in request

Situation:

  • T0: Google sends a request to the integrator with request ID ABC123.
  • T1: The integrator server receives this request and processes it successfully.
  • T2: Google's server loses power prior to receiving the response in T1.
  • T3: Google's server power is restored and the same request (ID ABC123) is sent. Unfortunately Google has an error and some of the parameters are different.

Outcome:

In this case the integrator server must reply with an HTTP 400 (BAD REQUEST) error code which denotes to Google that there is an error in this system.