APIs Sam API Asynchronous operations

This page explains how asynchronous operations work in the Skylark Access Management (SAM) API.

Asynchronous processing is used for batch operations where multiple accesses are created or updated in a single request. Instead of blocking until completion, the API returns a Task resource that clients must poll until a terminal state is reached.

This page focuses on behavior, lifecycle, and error semantics, not on repeating the OpenAPI specification.

What is an asynchronous operation in SAM

An asynchronous operation in SAM is a long-running background process that:

  • Is initiated by a client request
  • Continues executing after the HTTP request returns
  • Produces its result incrementally
  • Exposes its status and outcome through a Task resource

The Task acts as a tracking handle for the operation.

When asynchronous processing is used

Asynchronous processing is used for the following operations:

  • Batch access creation
    • POST /{tenantName}/access/batch
  • Batch access update
    • PATCH /{tenantName}/access/batch

Single-access operations are always synchronous.

Task resource (high level)

A Task represents the execution of a batch operation.

Key characteristics:

  • Each batch request creates exactly one Task
  • The Task has a stable ID (job-*)
  • The Task state evolves over time
  • Results and errors are attached to the Task, not returned via HTTP status codes

Tasks follow TMF-style async semantics.

Task lifecycle and states

A Task transitions through the following states:

StateMeaning
ACKNOWLEDGEDTask accepted, execution not started yet
IN_PROGRESSTask is currently executing
DONETask completed successfully
FAILEDTask completed with partial or full failures
REJECTEDTask rejected before execution
TERMINATEDTask stopped prematurely

Terminal states

A Task is considered final when it reaches one of the following states:

  • DONE
  • FAILED
  • REJECTED
  • TERMINATED

Clients must stop polling once a terminal state is reached.

Polling mechanics

After submitting a batch request, clients must poll the Task endpoint:

GET /{tenantName}/access/batch/{taskId}

Polling behavior

  • Polling is idempotent
  • The endpoint is safe to call repeatedly
  • The response payload depends on the current Task state

Recommended polling strategy:

  • Poll every few seconds
  • Stop once a terminal state is returned

Task response behavior by state

Non-terminal states

For the following states:

  • ACKNOWLEDGED
  • IN_PROGRESS
  • TERMINATED

The response contains only base Task information:

{
  "id": "job-12345",
  "state": "IN_PROGRESS",
  "@baseType": "task",
  "@type": "batchCreation"
}

No resources or errors are included.

DONE — successful execution

When the Task reaches DONE:

  • All accesses were processed successfully
  • The response includes the created or updated accesses
{
  "id": "job-12345",
  "state": "DONE",
  "accesses": [
    "..."
  ],
  "@baseType": "task",
  "@type": "batchCreation"
}

FAILED — partial success or failure

When the Task reaches FAILED:

  • Some accesses may have been created or updated
  • Some accesses may have failed
  • Both resources and errors can be present
{
  "id": "job-12345",
  "state": "FAILED",
  "accesses": [
    "..."
  ],
  "errors": [
    "..."
  ],
  "@baseType": "task",
  "@type": "batchCreation"
}

Partial success is a valid and expected outcome for batch operations.

REJECTED — execution never started

When the Task reaches REJECTED:

  • No accesses were created or updated
  • The batch was rejected before execution
  • Only errors are returned
{
  "id": "job-12345",
  "state": "REJECTED",
  "errors": [
    "..."
  ],
  "@baseType": "task",
  "@type": "batchCreation"
}

Error propagation rules

Important rules to understand:

  • HTTP status codes indicate request-level problems only
  • Business and execution errors are returned inside the Task
  • Batch execution errors never surface as HTTP 4xx/5xx

Idempotency and retries

  • Polling is always safe and read-only
  • Retrying batch requests creates a new Task
  • Prefer polling over retries

Common mistakes to avoid

  • Expecting immediate results from batch endpoints
  • Treating FAILED as a total failure
  • Ignoring partial successes
  • Continuing to poll after the job when it’s in a terminal state