Skip to content
Round RobinRound Robin

Conventions

The API uses pagination, timestamps and conditional requests to keep reads and writes consistent. Check each operation’s parameters before constructing a request.

You need: the credential required by the operation. See authentication.

Read every page

Section titled “Read every page”
Response shape Continue with
page, pageSize, totalPages The next page number, until totalPages
Cover requests with nextCursor That value as cursor, retaining the same from and to
Availability impact with nextAfterRotationId That value as afterRotationId

Do not infer completeness from an empty page. Check the response’s completion fields and any per-rotation limitations.

For lists with page and pageSize, page numbering starts at 1 and page size is at most 100. Supported sorting fields depend on the operation. Invalid sorting or paging parameters return 400.

Preserve interval boundaries

Section titled “Preserve interval boundaries”

Timestamps include their UTC offset. Duty and impact endpoints that require UTC accept offset zero; convert local dates and times before sending them.

Intervals use an inclusive start and exclusive end. Keep the returned boundaries when selecting a full duty interval. Check each operation’s range limit; candidate and impact previews accept at most 31 days.

Conditional reads

Section titled “Conditional reads”

When a read returns an ETag, retain it exactly, including quotes. For an operation supporting conditional reads, send it in If-None-Match; 304 means the cached representation remains valid.

Not every endpoint supports conditional reads. A returned ETag can also be the version needed for a subsequent write; it does not by itself establish support for If-None-Match.

Conditional writes

Section titled “Conditional writes”

Writes to existing rotations generally require If-Match. Send the current ETag from the resource or action preview.

Result What to do
428 precondition_required Supply the required header.
412 precondition_failed Read or preview again, review the current terms and retry with the new ETag.
409 write_conflict Refresh before retrying the unchanged intent.

The server accepts an ETag with a W/ prefix when its revision matches. Preserve the value as received.

If-Match: * permits a write against any current revision. Avoid it when retrying an action that could advance duty twice.

The one pair of writes that takes no precondition

Section titled “The one pair of writes that takes no precondition”

The rotation availability create and delete operations require neither If-Match nor Idempotency-Key. Repeating an absence create with the same person, period and appliesTo returns the existing absence.

Preview operations do not commit duty changes and do not require If-Match.

Creating things

Section titled “Creating things”

Creating a rotation uses Idempotency-Key instead of If-Match. Use a new identifier for each intended rotation and reuse it for retries. Replays within 24 hours return the existing rotation; a later reuse returns 409.

Duty arrangement, cover and swap actions use operationId in the body. Reuse the same body and identifier after an uncertain result. Changed terms need a new identifier. See participant duty operations.

Cache and poll

Section titled “Cache and poll”

Keep authenticated responses private to the caller. Conditional reads still count towards rate limits, including 304 responses.

Poll only as often as your integration needs, and respect Retry-After when returned.

Next steps

Section titled “Next steps”