How do I expose a BAW service flow as a REST endpoint for external systems (and secure it)?

Question

An external application needs to call business logic that lives in a BAW service flow (validate an order, look up a status). Can a service flow be exposed as a REST API, and how do we secure and version it?

Answer 1

A service flow is exposed by making it a startable service (Overview > Expose > as a startable service to a team); external callers then run it through the Process REST API - synchronously, with input and output data - no coach involved:

# run a service flow and get its outputs (BPM 8.5.x / BAW): serviceId = the service's id (1.xxxx), snapshotId or branchId for the tip
POST /rest/bpm/wle/v1/service/1.7a3f…?action=start&snapshotId=2064.…&params={"orderId":"ORD-42"}&parts=all
BPMCSRFToken: <token>
-> { "data": { "serviceStatus": "end", "data": { "valid": true, "messages": [] } } }
# BAW 21+: Process REST v2 (/bpm) has no service-start resource yet - service invocation stays on the classic v1 resource above

Practical rules for an API-like use:

• Stable address: callers should not know service ids and snapshot ids - put an API gateway (IBM API Connect, DataPower, NGINX) in front that maps POST /orders/validate to the BAW URL and injects the current snapshot id (or use branchId for the tip in development only). The gateway also handles API keys / OAuth for the callers and translates to BAW's basic auth / Zen API key + CSRF token.
• Contract: define the input / output business objects in a toolkit and publish an OpenAPI document you maintain (BAW does not generate one for arbitrary services); keep the service's parameters additive between versions.
• Security: expose the service to a dedicated team that contains only the technical user of the gateway; the technical user needs no other rights; TLS everywhere; audit calls at the gateway.
• Behaviour: keep it short-running (the HTTP call waits), throw typed errors (they come back as serviceStatus: error with the message), and make it idempotent - gateways retry.
• Alternatives: on CP4BA, an Application (Application Designer) or App Connect can front the same service with a proper REST contract; for event-style calls use a UCA + message instead of a synchronous service.

References

• Process REST API - service resource (start)
• BPMCSRFToken
• BAW documentation - exposing services