Exposing your ERP as a REST API with Boomi

Sooner or later someone asks for direct access to the ERP: the e-shop needs live stock, a partner wants order status, the sales app wants a customer’s open balance. The quick answer is to open the ERP’s own API to them. This article explains why that usually backfires, describes the pattern that works better, and then builds it step by step in Boomi.

The problem with exposing the ERP directly

ERP APIs are designed for the ERP, not for your consumers:

• They are shaped like the ERP’s database. Getting “a customer’s open balance” may take three calls and some arithmetic on the consumer’s side.
• They leak internals. Field names, codes and company numbers that only make sense inside your organisation end up in partner code.
• They change with the ERP. An upgrade or a move to a different ERP breaks every consumer at once.
• They need powerful credentials. ERP API users often have far more rights than a single consumer should have.

The pattern: an API facade

An API facade is a small, stable API that you design around what consumers need. Behind it, an integration layer translates each call into whatever the ERP requires.

Consumers ──► API facade (your contract) ──► integration logic ──► ERP

Consumers only see the facade. You can change, upgrade or replace the ERP, and as long as the facade keeps its contract, nobody outside notices.

Design the contract first

Before opening any tool, write the contract down. For this example we will expose one resource:

# Fragment of an OpenAPI description
paths:
  /customers/{customerId}/balance:
    get:
      summary: Open balance of a customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Balance found
          content:
            application/json:
              example: { "customerId": "C-1042", "currency": "EUR", "openBalance": 1250.40, "overdue": 310.00 }
        '404':
          description: No such customer

Notice what is not in the contract: ERP table names, internal company codes, or the fact that “overdue” is calculated from two different ERP documents. That logic belongs behind the facade.

Building it in Boomi

In Boomi, the facade is built from two pieces: an integration process that does the work, and an API Service component that defines the REST contract and routes each endpoint to a process.

Step 1: Build the process

1. Create a new process. Configure the Start shape with the Web Services Server connector and the Listen action.
2. In the operation, set the input type to None (a GET has no body) and the output type to Single JSON Object. Create a JSON profile that matches the 200 response in your contract.
3. Read the customer ID from the URL. Path parameters reach the process as dynamic document properties named after the parameter, prefixed with param_ (query parameters use query_). Here that is param_customerId.
4. Call the ERP with its connector (or the HTTP Client connector if your ERP exposes a REST API) to fetch the customer’s open items.
5. Use a Map shape to turn the ERP response into your JSON profile. This is where the translation happens: rename fields, calculate overdue, drop internal codes.
6. End with a Return Documents shape, so the result is sent back to the caller.

Step 2: Handle “not found” properly

If the ERP returns no customer, don’t send an empty 200. Add a Decision shape after the ERP call. On the “not found” branch, set the response status code to 404 through the Web Services Server document properties and return a short error body such as { "error": "customer_not_found" }. Consumers can then handle the case without guessing.

Step 3: Create the API Service component

1. Create a new API Service component and choose REST as the type.
2. Set the base path, for example /erp/v1. Putting the version in the path makes a future v2 straightforward.
3. Add a REST endpoint: method GET, resource path customers/{customerId}/balance, and select the process from step 1.
4. Review the generated API documentation. Boomi can export an OpenAPI description, which you can compare with the contract you wrote by hand.

Step 4: Deploy and secure the runtime

1. Deploy both the process and the API Service component to the same environment. The API only works if the runtime (an Atom, Molecule or Atom Cloud) has both.
2. In the runtime’s Shared Web Server settings, check the API type and the authentication. For a first test, Basic authentication with a dedicated user is enough. For production, put a gateway in front (see below).

Step 5: Test it

Call the endpoint with any HTTP client. Replace the host, port and credentials with your runtime’s values:

curl -u api-user:token https://your-runtime-host:9090/ws/rest/erp/v1/customers/C-1042/balance

You should get back the JSON from your contract, not an ERP document. Then try an unknown customer and check that you get a 404.

Before you go live

• Put a gateway in front. The runtime’s web server is not meant to face partners directly. A gateway adds API keys, rate limits and a developer portal. We cover that in Protecting an API with keys and rate limits in Boomi Cloud API Management.
• Use a least-privilege ERP user. The process only needs to read balances, so the ERP user it connects with should only be able to do that.
• Log a correlation ID. Return an ID in a response header and log it in the process, so a partner’s complaint can be traced to a specific execution.
• Keep the contract under version control. Treat the OpenAPI file as the source of truth, and review changes to it like code.

Summary

The facade pattern takes a little more design work up front, and pays it back the first time the ERP changes. In Boomi, the process holds the translation logic and the API Service component holds the contract, so each part can change without touching the other. For the bigger picture of where this fits, see our guide API management: what it is and when you need it.