AsyncFlow API Documentation

Overview

AsyncFlow is an asynchronous message processing API that accepts messages and processes them in the background. The API uses X-API-KEY authentication and provides status tracking for submitted messages.

Base URL: https://fakecomworld.endpoint/asyncflow

Processing Model: Asynchronous - messages are queued and processed by a background service

Authentication

AsyncFlow uses API Key authentication with the X-API-KEY header.

Default API Key (configurable): asyncflow-api-key

Required Headers

Header	Type	Required	Description
X-API-KEY	string	Yes	Your API key for authentication
X-STUDENT-GROUP	string	Yes	Your student group identifier
Content-Type	string	Yes (POST)	Must be application/json

Endpoints

Submit Message (Asynchronous)

Submit a message for asynchronous processing. The message is queued and processed by a background service.

Endpoint: POST /asyncflow

Request Body:

{
  "destination": "your message destination",
  "content": "Your message payload here",
  "priority": "normal"
}

Request Schema:

Field	Type	Required	Description
destination	string	Yes	Target destination
content	string	Yes	Message payload/content
priority	string	No	Message priority (informational only)

Success Response (202 Accepted):

{
  "accepted": true,
  "trackingId": "ASF-A1B2C3D4E5F67890ABCDEF1234567890",
  "message": "Message queued for processing",
  "submittedAt": "2024-01-15T10:30:00Z"
}

Response Schema:

Field	Type	Description
accepted	boolean	Indicates if the message was accepted for processing
trackingId	string	Unique tracking identifier (format: ASF-{32-char hex})
message	string	Status message
submittedAt	datetime	UTC timestamp when message was submitted

Get Messages for Student Group

Retrieve all messages submitted by a specific student group.

Endpoint: GET /asyncflow

Request Headers:

X-API-KEY: asyncflow-api-key
X-STUDENT-GROUP: your-group-name

Success Response (200 OK):

[
  {
    "trackingId": "ASF-A1B2C3D4E5F67890ABCDEF1234567890",
    "status": "Completed",
    "submittedAt": "2024-01-15T10:30:00Z",
    "processedAt": "2024-01-15T10:30:45Z",
    "errorDetails": null
  },
  {
    "trackingId": "ASF-B2C3D4E5F67890ABCDEF1234567890A1",
    "status": "Processing",
    "submittedAt": "2024-01-15T10:31:00Z",
    "processedAt": null,
    "errorDetails": null
  }
]

Get Message Status by Tracking ID

Retrieve the status of a specific message using its tracking ID.

Endpoint: GET /asyncflow/{trackingId}

URL Parameters:

Parameter	Type	Description
trackingId	string	The tracking ID returned when submitting the message

Success Response (200 OK):

{
  "trackingId": "ASF-A1B2C3D4E5F67890ABCDEF1234567890",
  "status": "Completed",
  "submittedAt": "2024-01-15T10:30:00Z",
  "processedAt": "2024-01-15T10:30:45Z",
  "errorDetails": null
}

Status Response Schema:

Field	Type	Description
trackingId	string	Unique tracking identifier
status	string	Current status: Queued, Processing, Completed, or Failed
submittedAt	datetime	UTC timestamp when message was submitted
processedAt	datetime	UTC timestamp when processing completed (null if still processing)
errorDetails	string	Error description if status is Failed, null otherwise

Message Status Flow

Messages progress through the following statuses:

1. Queued - Message has been accepted and is waiting to be processed
2. Processing - Background service is currently processing the message
3. Completed - Message has been successfully processed
4. Failed - Message processing failed

Processing Timeline:

• Messages remain in Queued status until picked up by the background service
• Background service checks for queued messages every 5 seconds (configurable)
• Processing time: 2-30 seconds (random, configurable)
• Chance of failure: 10% (configurable)

Error Responses

• 401 Unauthorized - Missing or invalid API key
• 400 Bad Request - Missing destination
• 400 Bad Request - Missing payload
• 400 Bad Request - Missing X-STUDENT-GROUP
• 404 Not Found - Message not found
• 403 Forbidden - Accessing message from different student group
• 429 Too Many Requests - Rate limit exceeded (check headers)
• 500 Internal Server Error
• 503 Service Unavailable
• 504 Gateway Timeout

Rate Limiting

AsyncFlow enforces rate limiting to ensure fair usage.

Limits: These are the default settings

• 10 requests per minute per student group
• Rate limit window: 60 seconds (sliding window)

When exceeded a 429 Too Many Requests is returned. Check the headers for additional information.

Background Processing

AsyncFlow uses a background service to process messages asynchronously:

Status Transitions

1. Message submitted → Status: Queued
2. Background service picks up message → Status: Processing
3. After processing delay:
   • Status: Completed
   • Status: Failed

Response Times

AsyncFlow simulates realistic network conditions & outages.

Support

For issues or questions, please contact your instructor or check the project documentation.