DEV Community

Alone Star
Alone Star

Posted on

LightESB PlatformHttp v3.0.0: JSONPath Order Transform HTTP Route Guide

#api #backend #tooling #tutorial

Metadata

  • Applicable Version: PlatformHttp@v3.0.0
  • Related Service: PlatformHttp@v3.0.0@platform-http-route.xml

PlatformHttp v3.0.0 provides a compact and practical HTTP transform pattern: receive order JSON, extract business fields with JSONPath, and return JSON responses with consistent encoding.

This article walks through how the route is designed and how to validate it quickly.

Background and Goal

In many integration services, the request entry must be strict and observable:

  • Keep a clear HTTP Listener entry for upstream systems
  • Extract key fields (orderId) as early as possible
  • Preserve service-level logs for troubleshooting
  • Return stable JSON without Chinese encoding issues

PlatformHttp v3.0.0 addresses these goals in one route package.

Route and Configuration Breakdown

1) Runtime listener switch and port

From common.config.properties:

server.port=18080
HTTP.Listener=true
system.components=undertowhttp
Enter fullscreen mode Exit fullscreen mode

Meaning:

  • HTTP.Listener=true enables Undertow registration
  • server.port=18080 defines the external listening port
  • route endpoint resolves with this port at runtime

2) Service identity and URL versioning

From service.config.properties:

service.name=PlatformHttp
service.version=3.0.0
Enter fullscreen mode Exit fullscreen mode

The main request entry uses:

<from uri="undertow:http://0.0.0.0:{{server.port}}/{{service.version}}/transform/order?httpMethodRestrict=POST" />
Enter fullscreen mode Exit fullscreen mode

So the final request path is:

  • POST /3.0.0/transform/order

This keeps API versioning explicit in URL paths.

3) JSONPath extraction and response write-back

The route extracts orderId in multiple ways, then writes a JSON response:

<log message="orderId (JSONPath): ${jsonpath($.orderId)}"/>
<setProperty name="extractedOrderId"><jsonpath>$.orderId</jsonpath></setProperty>
<setHeader name="OrderId"><jsonpath>$.orderId</jsonpath></setHeader>
...
<transform><simple>{"status": "success", "message": "请求处理完成"}</simple></transform>
<process ref="jsonResponseProcessor"/>
<setHeader name="Content-Type"><constant>application/json</constant></setHeader>
Enter fullscreen mode Exit fullscreen mode

Why this design works:

  • HTTP Listener: one explicit request entry point
  • Request entry observability: servicelog captures headers and body
  • Downstream forwarding ready: extracted fields can be reused for later routing decisions
  • Response write-back stability: jsonResponseProcessor improves UTF-8 output behavior

Request and Response Validation

API 1: Main transform route 

curl -X POST "http://localhost:18080/3.0.0/transform/order" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-001\",\"amount\":299.50}"
Enter fullscreen mode Exit fullscreen mode

Expected response:

{"status":"success","message":"请求处理完成"}
Enter fullscreen mode Exit fullscreen mode

API 2: JSONPath-inline response sample 

curl -X POST "http://localhost:18080/3.0.0/transform/order1" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-002\"}"
Enter fullscreen mode Exit fullscreen mode

Expected response:

{"status":"ORD-20260409-002","message":"请求处理完成"}
Enter fullscreen mode Exit fullscreen mode

Common Issues and Troubleshooting

1) Port not reachable

Check:

  1. HTTP.Listener=true
  2. server.port=18080
  3. no other process occupies 18080

2) Method rejected (405)

  • the endpoint restricts method with httpMethodRestrict=POST
  • call must use POST

3) Incorrect path or version

  • route path includes {{service.version}}
  • ensure request URL matches /3.0.0/transform/order or /3.0.0/transform/order1

4) Encoding or garbled response text

  • keep jsonResponseProcessor in the response path
  • keep Content-Type: application/json response header

Summary

PlatformHttp v3.0.0 demonstrates a practical baseline for API integration routes:

  • strict HTTP Listener entry
  • early JSONPath field extraction
  • service-level request tracing
  • stable UTF-8 response write-back

This pattern is suitable for order transform gateways and can be extended with validation, auth checks, and downstream forwarding policies.

Related Reading

Top comments (0)