Model a run as a durable resource
A business process API describes an agreement between a client and a workflow. Distinguish the business object from a processing run. The same package can have several runs as inputs or rules change, while each accepted run refers to one specific input set and process version.
Define the outcome the client can rely on. Accepted means that work has entered the system under its contract; it does not mean that every step has completed. Keep extraction, review, and publication separate when they represent different business permissions.
Make the lifecycle observable
Give a run a stable identity and a status representation with documented states. Keep item-level progress separate from the overall lifecycle. Define how partial results, cancellation, and unresolved errors affect the run's final disposition.
In the reference design used here, a submission returns an accepted response with a run identifier, and a status operation exposes its state. The job lifecycle reference explains the transitions. These are implementation patterns to adapt, not endpoints for a hosted ProcessAPI.com service.
Protect intent and access
Use an explicit idempotency contract to associate repeated submissions with the same intended operation. State the key scope, retention behavior, and response to conflicting request content. Protect downstream side effects independently; submission deduplication alone does not solve every repeat-execution problem.
Authorize access to each run and artifact, not only to the route name. A caller allowed to submit one account's work should not automatically read another account's outputs. Keep approval permissions distinct from worker execution rights when the process requires it.
Describe the contract before implementing it
Write schemas, example responses, error codes, and compatibility rules in a reviewable interface description. Keep the API version distinct from the version of the business process. A changed extraction rule can produce different results even when endpoint names remain the same.
The API design playbook develops the complete pattern. Start with the reference quickstart and sample files, then adapt authorization, persistence, and recovery to your own system. Clear documentation is part of the design, not evidence that the service has already been implemented.