Building Your First Integration

This guide builds on the Quickstart. It shows how to build a practical REST API integration that receives HTTP requests, processes the data, and returns a response.

Prerequisites#

Complete the Quickstart first. You need:

• The Weik.io devcontainer running in VS Code
• The weikio CLI configured
• A basic understanding of how Apache Camel routes work

What you’ll build#

You’ll build an integration that:

1. Exposes a REST endpoint at /api/orders
2. Accepts POST requests with JSON payloads
3. Parses the data and adds a timestamp
4. Logs the result

Create the integration#

Create an integrations directory if you don’t have one, then initialize a new integration:

mkdir -p integrations
cd integrations
weikio integration init order-api

View the default integration:

cat order-api/integration.camel.yaml

Build the REST endpoint#

Edit order-api/integration.camel.yaml and replace its contents:

- from:
    uri: "platform-http:/api/orders"
    parameters:
      httpMethodRestrict: "POST"
    steps:
      - log:
          message: "Received order: ${body}"

      - unmarshal:
          json: {}

      - setHeader:
          name: orderId
          simple: "${body[id]}"

      - setHeader:
          name: orderDate
          simple: "${date:now:yyyy-MM-dd HH:mm:ss}"

      - setBody:
          simple: |
            {
              "orderId": "${header.orderId}",
              "status": "received",
              "timestamp": "${header.orderDate}",
              "message": "Order processed successfully"
            }

      - marshal:
          json: {}

      - log:
          message: "Processed order ${header.orderId} at ${header.orderDate}"

This integration:

• Listens for POST requests at /api/orders
• Logs the incoming request body
• Parses the JSON payload
• Extracts the order ID and adds a timestamp
• Returns a JSON response with order confirmation
• Logs the processed result

Test locally#

Run the integration locally:

weikio integration run order-api

In a separate terminal, test the endpoint:

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ORD-12345",
    "customer": "John Doe",
    "items": [
      {"product": "Widget", "quantity": 2}
    ]
  }'

Expected response:

{
  "orderId": "ORD-12345",
  "status": "received",
  "timestamp": "2025-11-12 08:30:45",
  "message": "Order processed successfully"
}

Check the console logs to see the integration processing the request.

Press q to stop the local integration.

Deploy to Weik.io#

Push the integration to the platform. From the integrations directory (the parent of your integration folder):

weikio integration push order-api

Verify the deployment:

weikio integration flows ls

Start the integration:

weikio integration flows start order-api

Test the deployed integration#

Once running, the integration is accessible through the Weik.io platform.

Check the UI to view:

• Integration status
• Request logs
• Processing metrics

Adding error handling#

For production integrations, you can add validation and error handling using Camel’s choice and when steps. The basic integration above demonstrates the core REST API functionality.

To add validation, you can:

• Use Camel’s Bean Validation component for schema validation
• Add choice steps with simple expressions for business logic validation
• Use doTry/doCatch for exception handling
• Return appropriate HTTP status codes using the CamelHttpResponseCode header

For more advanced error handling patterns, see:

• Apache Camel Error Handler Documentation
• Apache Camel Bean Validation

Common patterns#

Database integration#

Add database operations:

- to:
    uri: "sql:INSERT INTO orders (order_id, data, created_at) VALUES (:#${header.orderId}, :#${body}, NOW())"

External API calls#

Call external APIs:

- to:
    uri: "https://api.example.com/validate"
    parameters:
      httpMethod: POST
- unmarshal:
    json: {}

Message transformation#

Transform data formats:

- marshal:
    json:
      prettyPrint: true
- to:
    uri: "file:/data/orders"

Async processing#

Process requests asynchronously:

- wireTap:
    uri: "seda:process-async"
- setBody:
    constant: '{"status": "queued"}'

Troubleshooting#

Integration won’t start#

Check the status:

weikio integration flows status order-api

View detailed logs in the Weik.io UI.

Port conflicts#

If port 8080 is in use locally, the integration will show an error. Stop other services or change the port configuration.

JSON parsing errors#

Verify your JSON is valid:

echo '{"id": "test"}' | jq .

Use the error handling patterns above to catch and handle invalid JSON.

Next steps#

You’ve built a practical REST API integration. Explore more features:

• Integration Services: Create reusable service components
• Entity Store: Track changes to your data
• Using Variables: Manage configuration
• Apache Camel Components: Connect to 300+ systems