Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: A REST-to-SOAP Gateway with Token Authentication

Build a gateway that gives a legacy SOAP bank service a JSON REST face - signed bearer tokens, a SOAP security header, fault mapping, request ids and rate limiting - in plain Node.js.

This project combines the migration and integration chapters into one working piece of infrastructure: a gateway that exposes a legacy SOAP "account" service to modern clients as a JSON REST API. Outside, callers present a bearer token. Inside, the gateway calls the SOAP service with the credentials that service expects, translates responses and faults, tags every call with a request id, and protects the back end with a rate limit.

The pieces are small, and each is useful alone. You will first build and test the two security helpers (token signing and rate limiting), then assemble the full gateway.

The tokens here are a teaching simplification: an HMAC-signed payload similar to a JWT, built with node:crypto. In production use a standard library and an identity provider, rotate keys, and keep the signing secret out of source code. The SOAP security header below is a simplified username-and-password header; real services use WS-Security's UsernameToken with digests or X.509 signatures.

Architecture

sequenceDiagram
  participant C as REST client
  participant G as Gateway
  participant S as SOAP service
  C->>G: GET /accounts/42/balance (Bearer token)
  G->>G: verify token, rate limit, add request id
  G->>S: SOAP GetBalance + security header
  S-->>G: envelope or Fault
  G-->>C: JSON 200 / 404 / 429 / 502

The gateway is the only component that knows both worlds.

Step 1: tokens and rate limiting

A signed token has two parts: a base64url payload (who, until when) and an HMAC of that payload. Verification recomputes the HMAC and compares it in constant time. The rate limiter is a fixed window per client that counts calls.

Node.js Token signing and a rate limiter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first four lines show the failure reasons the gateway will turn into 401 responses. The rate limiter lets three calls through and rejects the next two, then resets when the window passes. (For a real fleet of gateways the counters live in Redis or similar, so that every instance shares them.)

Step 2: the full gateway

Now the pieces are assembled: a SOAP account service that requires a username and password in its header; a gateway with authentication, rate limiting, request ids and fault mapping; and a client that exercises the happy path and each failure.

Node.js The complete gateway

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Study the order of checks in the gateway: authenticate first, then rate limit, then route, then call the back end. Cheap rejections come first, so abusive traffic never reaches the expensive part. And notice that the SOAP credentials (svc-gateway) never leave the gateway: REST clients hold only their own token.

Improvements to consider

  • Replace the header with WS-Security. A real service wants wsse:UsernameToken or a signed timestamp; the gateway builds it per call.
  • Cache balances for a few seconds with a short TTL if freshness allows, and send Cache-Control accordingly.
  • Circuit breaker: after several 503s in a row, stop calling the back end for 30 seconds and answer immediately.
  • Observability: log request id, subject, route, upstream status and duration as one JSON line per call, never the token itself.
  • Idempotency: for state-changing routes, accept an Idempotency-Key header and pass it into the SOAP message (see Versioning and Evolving SOAP Services).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order should a gateway perform its checks?

    Cheap rejections come first so invalid or abusive requests never consume back-end capacity.
  2. 2. Why compare signatures with timingSafeEqual?

    A normal string comparison stops at the first difference, which can reveal how much of a guess was right.
  3. 3. The SOAP back end returns the fault BACKEND_DOWN (a Server fault). Which REST status fits best?

    The failure is on the service side, so a 5xx status such as 503 Service Unavailable tells clients it is not their mistake.
  4. 4. Why does the gateway add a correlation id to the SOAP header?

    The same id in the REST response header and the SOAP message links the log lines of both sides.

Summary

  • A gateway gives a legacy SOAP service a REST face and keeps back-end credentials private.
  • Authenticate, rate limit, route, then call the back end; translate faults to status codes.
  • Use signed tokens verified with constant-time comparison, and rate limits per subject.
  • Add a request id, timeouts, and structured logs; consider caching and circuit breakers.

Next: Project: An Order Service with Typed Faults and Idempotency