HTTP is a stateless application-layer protocol for requests and responses between networked clients and services. For workflow APIs, its broad support lets browsers, mobile apps, backend services, and command-line tools communicate without a specialized client library. section 2.3.3
A workflow API can use POST to submit data for processing, GET to retrieve a resource, headers for authentication and content type, and status codes to report errors. JSON provides a structured, readable response format that clients across languages can parse. section 2.3.3 section 2.3.4
Choose the interaction pattern to match the workflow’s timing:
- Synchronous: send a request and wait for the result when processing takes only a few seconds, such as categorizing a product image. section 2.3.4
- Asynchronous: submit a long-running task, receive a job identifier and status URL, then retrieve progress and the completed result. section 2.3.4
- Streaming: deliver output progressively using Server-Sent Events, so a conversational client can display tokens as they arrive. section 2.6 section 2.3.4
curl -X POST https://api.company.com/categorize-image \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-proj-abc123" \
-d '{
"image_url": "https://storage.example.com/images/product-123.jpg"
}'A synchronous image-categorization request sends JSON in a POST body and supplies a bearer token in the Authorization header. section 2.3.4
{
"job_id": "job_8x7f9k2m",
"status": "processing",
"status_url": "/jobs/job_8x7f9k2m",
"estimated_duration": "10-15 minutes"
}A research submission returns a job ID and status URL instead of making the client wait for the report. section 2.3.4
data: {"token": "Please"}
data: {"token": " bring"}
data: {"token": " your"}
data: {"token": " insurance"}
data: {"token": " card"}A streaming response delivers successive tokens as event data rather than waiting for the complete answer. section 2.3.4
External HTTP APIs and internal service calls can make different tradeoffs. An API gateway centralizes external concerns such as authentication and rate limiting. For frequent internal calls, gRPC with Protocol Buffers offers generated service interfaces and avoids repeated JSON serialization. section 2.6 section 2.4.2










