Complete an integration brief using a report request

Describe an integration through one complete flow before comparing proposals. “The portal needs an API connection” leaves open which data moves, when the work is complete and who handles a failure. A completed brief makes these decisions possible to discuss.

Set one flow for the first delivery

In this fictional project, a portal requests a monthly PDF report from a document service. All names, fields and responses are our own examples, not a provider’s API.

This also makes extra requests visible: a later email feature would be a separate step with its own failure handling. It does not disappear inside the word “connection”.

Supply inputs with values and meanings

The following sample body is agreed for POST /report-jobs:

{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}

The request ID identifies this creation request. Project and template are stable references; the period here is a calendar month in year–month format. Display names or a free-text period do not replace these values. The portal must establish with the document service which templates are approved.

Access to the job, status and file is limited to the authorised project. Knowing a link alone does not permit a download. The brief specifies roles and the access method; actual tokens and passwords stay outside the document.

Describe acceptance and outcome separately

After durable acceptance, the example service replies with HTTP 202 and Location: /report-jobs/J-52:

{"jobId":"J-52","status":"queued"}

MDN describes 202 as acceptance of processing that has not finished. Our own contract therefore has queued (waiting), running (being processed), succeeded (completed successfully) and failed (unsuccessful) states. The job succeeds only once the file is created and, at completion, retrievable with authorisation. Microsoft describes a separate status query for asynchronous work; the specific state names here are our choice.

The same request ID with identical content in the same authorised scope refers to the same job. For different content, the example agrees on HTTP 409. This repetition rule must be implemented and checked; the field name alone does not create idempotency.

Fill four acceptance cases before implementation

In the last case, the platform team checks the template. A corrected new request gets a new request ID; the failed job remains traceable. If only the status query is unavailable, the portal shows that the current state is unknown and claims neither success nor failure.

Resolve open operating questions before committing

Add expected job volume, typical file size, acceptable wait, polling interval and retention for files and status data based on actual use. These values remain open in this example and must be resolved before a dependable commitment. An estimated duration is not adopted as a measured property.

An OpenAPI description can make operations, inputs and expected responses precise. The business definition of the outcome and team responsibilities must also be settled. With the completed cases, the portal and platform teams can assess the same delivery.

Sources

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses