Polling Job Token API

Overview

You know the WeatherForecast code you get when you type dotnet new webapi? Well, this sample starts with that but also demonstrates a token-based polling pattern for long-running operations (LROs). Instead of forcing clients to wait for work to finish synchronously, the API accepts a request, immediately acknowledges it with 202 Accepted, and hands back an operation token that the caller can poll. You can easily replace the WeatherForecast code with your own long running code -- you may not need to change anything else!

Both the Microsoft REST API Guidelines and Google Cloud APIs recommend this approach for operations that may take seconds or minutes to complete.

Why Polling?

• POST /jobs records the work request and returns quickly.
• The response carries a token (or operation URL) that uniquely identifies the job.
• Clients poll /jobs/{id} at their preferred cadence.
• The server reports status along the way:
  • 202 Accepted while processing is in progress.
  • 200 OK (or 201 Created) with the final payload when the job completes.
  • 4xx/5xx if the job fails.

This design decouples client responsiveness from job duration, supports retries naturally, and keeps server resources free from long-held connections.

Project Structure

• Controllers/JobsController.cs orchestrates job submission, cancellation, and status checks.
• Services/IJobProcessor.cs and implementations represent long-running work.
• Services/IJobStore.cs encapsulates job persistence; InMemoryJobStore and CachedJobStore illustrate different storage approaches.
• Models/JobResult.cs and Models/JobStatus.cs define the data contracts returned by the API.

App specific code

• AppModels/WeatherForecastRequest.cs and Models/WeatherForecastResponse.cs capture the polling job input and payload delivered on completion.
• AppServices/WeatherForecastJobProcessor.cs is the long running process -- replace this with your code.

Prerequisites

• .NET SDK 10.0 (preview) or later to match the target framework specified in api.csproj.
• PowerShell 7+ (optional) for the demo script in scripts/demo-weather.ps1.

Getting Started

1. Restore dependencies:

   dotnet restore

2. Run the API locally:

   dotnet run --project api

3. The service listens on the URL defined in Properties/launchSettings.json (by default https://localhost:7182).

Template Usage

To create a new project based on this template, run the following command:

dotnet new webapi-polling -o <myProject>

Core Workflow

1. Submit a job

   POST /jobs
   Content-Type: application/json
   
   {
     "city": "Seattle",
     "date": "2025-11-08"
   }

   Example response:

   HTTP/1.1 202 Accepted
   Location: /jobs/7b57f728-7f66-4f7f-a788-4c9b6e0a6f1c
   Retry-After: 2
   
   {
     "jobId": "7b57f728-7f66-4f7f-a788-4c9b6e0a6f1c",
     "status": "Pending"
   }

   The date field is optional; when omitted the processor selects a default forecast date.

2. Poll for status

   GET /jobs/7b57f728-7f66-4f7f-a788-4c9b6e0a6f1c

   Possible responses:

   • 202 Accepted with a body containing the current JobStatus.
   • 200 OK with the final JobResult, whose data property holds a WeatherForecastResponse payload:

      {
        "jobId": "7b57f728-7f66-4f7f-a788-4c9b6e0a6f1c",
        "status": "Completed",
        "data": {
          "city": "Seattle",
          "date": "2025-11-08",
          "temperatureC": 11,
          "summary": "Totals decrease overnight"
        }
      }

   • 404 Not Found if the token is unknown or has expired.

3. Handle completion or failure

   • On success, persist or display the returned result.
   • On failure, inspect the error payload and decide whether to retry the original submission.

API Surface

Method	Route	Description
POST	/jobs/weather	Submit a new long-running job request.
POST	/jobs/lottery	Submit a new long-running job request.
GET	/jobs/{id}	Retrieve current status or final result.
DELETE	/jobs/{id}	Cancel a job that is still in progress.
DELETE	/jobs/{id}?purge=true	Cancel and Delete a job from the cache.

Sample requests are captured in api.http, which can be executed with the VS Code REST Client extension or with tools such as curl/Invoke-WebRequest.

Demo Script

Run scripts/demo-weather.ps1 to see the polling pattern end-to-end. The script submits a weather forecast job, polls until completion, and prints the resulting forecast.

Testing the Workflow

• Use the demo-weather.md playbook to follow manual test steps.
• Add integration tests that mimic the polling loop by verifying transitions from Pending → Running → Completed/Failed in JobStatus.

References

• Microsoft REST API Guidelines (long-running operations section)
• Google Cloud API Design Guide (operation resources)

These documents inspired the token-based polling approach implemented here.