Implementing REST and SOAP APIs
Implementing REST and SOAP APIs
This domain tests exposing and consuming APIs in ACE: REST API projects and OpenAPI descriptions, HTTPInput/HTTPReply and RESTRequest, plus SOAPInput/SOAPReply and SOAPRequest with WSDL. You must implement the contract, not merely a flow that happens to return JSON or XML.
Core rules
- A REST API project starts from an OpenAPI document. Each operation must be implemented by a flow with the matching method and path; path parameters such as
/customers/{id}must be read from the local environment or input tree and validated. - Use HTTPInput and HTTPReply for synchronous HTTP. Return the correct status code and
Content-Type; do not send a 200 with an error body. - Use RESTRequest for outbound REST calls, ideally with an OpenAPI or policy for the endpoint and security. Handle non-2xx responses explicitly.
- For SOAP, SOAPInput and SOAPReply implement a WSDL operation. SOAPRequest invokes a provider; SOAP faults must be mapped to a meaningful response or failure path.
- Keep API security, credentials, and endpoint URLs in policies so they can change by environment.
Worked example
A GET /customers/{id} operation calls a backend REST service. The HTTPInput flow reads the id path parameter, validates it, calls RESTRequest using a policy-backed URL, and maps the JSON response to the API schema. If the backend returns 404, the flow returns 404 with an error body; if it returns 500, the flow returns 502 or 500 according to the API contract and logs the backend status. The HTTPReply node supplies the status and headers.
Traps
Implementing only the happy path leaves undefined operations. Hardcoding the base URL breaks promotion. Returning backend errors as 200 misleads clients. For SOAP, ignoring faults or WSDL namespaces causes schema validation failures.