APIs & Systems Integration
An environmental testing lab's results API, bridged to a partner with retries and dead-letter capture.
Fictionalised summary. Company names, the contact email and repository addresses are placeholders; no credential or token values are shown.
Domain & SKU
What this example orders, at a glance.
- Domain
- APIs & Systems Integration
- Deliverable
- API & Webhook Integration
- Turnaround
- Standard (48 hours)
- Environments in scope
- Linux VM
- Compliance
- None apply
02
Current State
Baseline architecture, stack, repository context and known friction.
Architecture & system context
Our lab system exports sample results to a partner API through a brittle manual script. A cron job polls a pending_events table and sends each event with curl, with no retries and no logging; when the partner is slow the events are lost. The partner side has a small consumer service that is not yet safe against duplicate deliveries.
Tech stack, frameworks & versions
- Python 3.11
- Flask 3.0
- SQLite
- cron + curl script
Known issues, error logs & friction
The manual script marks events as sent even when the partner call fails, so we drop notifications and find out from the partner days later. There are no retries, no dead-letter store and no shared event state between the two repositories.
Primary repository or architecture link
https://github.com/your-org/your-repoCurrent endpoints & integrations
- LIMS result export into the pending_events table
- Partner result-notification API (signature-check stub)
- Consumer service in the companion repository
03
Target State
Deliverable expectations, measurable benchmarks and definition of done.
Deliverable expectations
Replace the manual script with an event-driven bridge that has an exponential-backoff retry policy and persistent event state, sends exhausted events to a dead-letter file with the original payload for replay, and makes the consumer idempotent so duplicate deliveries are safe. A BRIDGE.md documents the flow end to end.
Quantifiable benchmarks & success metrics
Retries with exponential backoff up to a maximum attempt count; no event dropped; duplicate deliveries handled safely; replay documented.
Definition of done
The bridge replaces the script, retries and dead-letters events, the consumer is idempotent and tested, BRIDGE.md documents the flow, and the tests pass in CI.
Target contracts, auth & payload schemas
The bridge reads pending events from the LIMS database and posts each result notification to the partner API over HTTPS with a signature header. Events carry a stable idempotency key so the consumer can safely ignore duplicates. Authentication uses a shared signing secret referenced from the environment.
Retry, idempotency & dead-letter requirements
Five retries with exponential backoff and a maximum attempt cap, then a replayable dead-letter file.
04
Constraints
Forbidden changes, compliance, regions, freeze windows and deadlines.
Forbidden modifications & boundaries
Do not change the partner API contract or the consumer's public routes; do not post to the live partner endpoint during testing.
Compliance standards
- None apply
Approved regions & environments
- Linux VM in the us-east region
Freeze windows & blackout periods
No production changes Fri 17:00 to Mon 08:00 US Eastern.
Pinned libraries, versions & standards
Stay on Python 3.11 and Flask 3.0; no new runtime dependencies without review.
Target deadline or milestone
28 October, before the partner's quarterly data exchange.
Auth standards & secret management
Shared signing secret from the environment; no credentials in code.
05
Access & Verification
Repository access, read-only credentials, environments and verification.
Handover method
Repository access
Git repository URL
https://github.com/your-org/your-repoGit repository URL (companion repository)
https://github.com/your-org/your-repo-2Read-only repository token
Encrypted in your browser before it leaves the device.
Environments in scope
- Linux VM
Sandbox API base URLs
Both repositories under github.com/your-org; partner sandbox base URL stub.
Contact email
Acceptance criteria as captured
These are the testable statements fixed before payment. Delivery is checked against this list.
- The manual script is replaced by a bridge with a retry policy (exponential backoff, maximum attempts) and persistent event state.
- Exhausted events land in a dead-letter file with the original payload for replay.
- The consumer side is idempotent: duplicate deliveries are safe, documented and tested.
- `BRIDGE.md` documents the event flow end to end across both repositories.
From the live intake
Captured screenshots of this work order being filled in. Each image is scrollable — scroll inside a frame to see the full page.
What happens after payment
Payment confirms the fixed scope. From there the work runs to the SLA you selected and every step is visible on your private dashboard.
The SLA clock starts
Your turnaround countdown begins the moment payment is confirmed — under 14 hours overnight, or 48 hours standard. Early delivery is always the goal.
A private dashboard
Your tracking link opens a private work-order dashboard showing the five delivery stages and every update as the work progresses.
Verified delivery
The deliverable is returned as a verified pull request or documented package, checked against the acceptance criteria you agreed before payment.
Your downloads
The final report, the acceptance-criteria results and every file in the delivery package are available on the dashboard until you close it.