async-api-patterns

Implements asynchronous REST patterns for long-running operations using polling, webhooks, and SSE.

Updated Jun 25, 2026
One-click install
npx skills add https://github.com/oriddd/ai-toolkit --skill async-api-patterns-oriddd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: async-api-patterns
Source: https://github.com/oriddd/ai-toolkit/tree/main/copilot/public/skills/async-api-patterns
Command: npx skills add https://github.com/oriddd/ai-toolkit --skill async-api-patterns-oriddd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Standard REST calls must return within 1-2 seconds, but operations like PDF generation or data export take longer. This Skill provides proven patterns to handle long-running operations without blocking HTTP threads or degrading API responsiveness. ## Core Features & Use Cases - Submit-Poll-Result Pattern: Return 202 Accepted with a jobId and Location header, expose a status endpoint with a clear state machine (PENDING, PROCESSING, COMPLETED, FAILED), and support long polling via Wait-For headers. - Webhook Notifications: Let clients provide a callbackUrl, sign payloads with HMAC-SHA256, and retry failed callbacks with exponential backoff before moving to a Dead Letter Queue. - Server-Sent Events: Push real-time status updates to UI clients over a single HTTP connection using Spring Boot SseEmitter. - Use Case: A client requests a large data export. The API returns 202 with a jobId, the client polls the status endpoint or receives a signed webhook when done, then downloads the artifact from a separate URL. Old jobs are cleaned up automatically via TTL. ## Quick Start Apply the async-api-patterns skill to design an asynchronous endpoint for my long-running report generation operation.

Frequently Asked Questions about async-api-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle long-running operations in a REST API?

Use the Submit-Poll-Result pattern: return 202 Accepted with a jobId and Location header, expose a status endpoint returning PENDING, PROCESSING, COMPLETED, or FAILED, and provide a separate download URL once the job completes.

How to implement webhooks for async job notifications?

Let clients supply a callbackUrl at submission, then POST the result when the job finishes. Sign the payload with HMAC-SHA256 in an X-Hub-Signature header, and retry failed deliveries with exponential backoff before moving to a Dead Letter Queue.

When should I use SSE instead of polling for status updates?

Use Server-Sent Events for UI clients needing real-time updates over a single HTTP connection, such as with Spring Boot SseEmitter. Avoid polling for high-frequency updates; reserve polling for low-frequency status checks.

How do I prevent duplicate async jobs from the same request?

Design for idempotency by hashing the job input. If a client submits the same job twice with an identical input hash, return the existing jobId instead of starting a new process.

What happens to abandoned async jobs and old artifacts?

Apply a TTL to automatically delete job metadata and artifacts after N days, and allow clients to DELETE a job to cancel processing. This prevents unbounded growth of database rows and storage.