Idempotency

At Gusto we have object based versions for idempotency.

Versions are essentially snapshots of a given resource. If things change, we want you to find out immediately. We'd rather have an extra HTTP request or two than employees receiving incorrect pay.

Object Layer

Idempotency

Requests are idempotent, meaning identical requests will only update the data once. This applies both to retrieving information (via GET requests) as well as updating information in the Gusto ecosystem (via POST requests.)

In practice, this allows you to try identical requests multiple times without fear that data will be altered multiple times. This also means that any updates will overwrite the existing data, instead of allowing additive or incremental changes.

Example

Let's say you wish to give Frank (with id 7) a $200 bonus for the current pay period. Unbeknownst to you, another application has already given Frank a $150 bonus. You make a request to the 'Update Payroll' endpoint with a bonus of "200.00".

Your request overwrites any bonus ($150) already in our system for employee 7 for the February 1 - 15 pay period.

Frank is now scheduled to receive a bonus of $200, which is $150 less than the combined value of the individual bonuses. While this may be good news for Accounting, it is obviously unacceptable.

Objects returned from the Gusto API include a version field that denotes which version of the object you hold. This version is calculated based on all updatable attributes of this and child objects.

When updating an object, you must include this version . If the data has changed since the last time you made a request, we will respond with the HTTP status code 409 Conflict

Note: Since versions are only updated when attributes that are updatable change (as opposed to any data returned by the API), they should not be relied on to monitor any change in the Gusto database. Their design is centered around preventing race conditions and overwriting data that the request couldn't have known has changed.