Weik.io

Building Your First Integration

Build a practical REST API integration that processes data

This guide builds on the Quickstart by creating a practical REST API integration that receives HTTP requests, processes data, and stores results.

Prerequisites

Complete the Quickstart guide first. You should have:

  • The Weik.io devcontainer running in VS Code
  • The weikio CLI configured
  • Basic understanding of Apache Camel integrations

What You’ll Build

An integration that:

  1. Exposes a REST endpoint at /api/orders
  2. Accepts POST requests with JSON order data
  3. Validates and transforms the data
  4. Logs the processed order

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 will be accessible through the Weik.io platform.

Check the UI to view:

  • Integration status
  • Request logs
  • Processing metrics

Next Steps with 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:

Next Steps

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

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 gracefully.