Documentation

X-Road Communication Protocol

SOAP and REST message requirements relevant to NRDEX implementations, based on the Suomi.fi Data Exchange Layer guidance.

Purpose

This page summarizes the communication protocol expectations used in X-Road-style exchange environments and highlights the requirements most relevant to NRDEX service providers and consumers.

Source basis: Suomi.fi X-Road communication protocol

Why this matters for NRDEX

Joining an exchange layer requires more than exposing an API. Systems must send and receive messages in the protocol format expected by the exchange environment. In practice, that means:

  • required transport headers
  • structured service identifiers
  • protocol-specific request and response handling
  • compatible interface descriptions

In an X-Road-style deployment, application systems do not talk directly to each other over the trust boundary. Requests pass through Security Servers, which apply the exchange-layer controls for authentication, protocol handling, signing, logging, and traceability.

SOAP protocol highlights

The Suomi.fi guidance describes SOAP as requiring X-Road-specific header content in addition to the SOAP body itself.

HTTP header expectations

  • X-Road SOAP uses SOAP 1.1
  • Content-Type should be text/xml or multipart/related
  • SOAPAction may be a valid quoted URI or an empty quoted value

Message structure

SOAP requests and responses should include protocol header elements identifying:

  • client
  • service
  • request identifier
  • user identifier where relevant
  • protocol version

The referenced guidance notes that the response should contain the same header data as the request, and that protocolVersion is required. For current X-Road SOAP usage, the protocol version is 4.0.

Interface description

SOAP services are expected to be described with WSDL. XML schema definitions can be embedded in the WSDL or provided separately through XSD files.

REST protocol highlights

The referenced guidance describes REST as lighter in terms of mandatory headers, but still governed by explicit exchange-layer routing rules.

Required header

  • X-Road-Client

The guidance also recommends using Content-Type, Accept, and a unique request identifier header.

Request format

REST requests are routed through a protocol path that includes:

  • HTTP method
  • protocol version
  • service identifier
  • optional path
  • optional query parameters

The referenced material describes REST protocol version r1 as the expected path component until updated. In practical terms, the routing path follows the pattern:

  • /{protocolVersion}/{serviceIdentifier}/{resourcePath}

Interface description

REST services should be described with OpenAPI 3 so they can be discovered and validated consistently in the exchange environment.

Error handling

The source material describes separate error handling patterns for SOAP and REST:

  • SOAP may return standard SOAP faults or non-technical SOAP errors
  • SOAP fault details may include a UUID that can be used to locate the specific failure in security server proxy logs
  • REST uses HTTP status codes, with exchange-layer errors surfaced through specific headers when the security server is the failing component
  • REST implementations should expect standard HTTP error patterns such as 400 for request validation failures and 413 for payload-size violations where configured limits are exceeded

For NRDEX implementations, this means consumers should distinguish between:

  • provider-side business or system errors
  • invalid protocol usage
  • exchange-layer or security-server failures

Traceability and audit linkage

Request traceability is part of the protocol model, not just an operational add-on.

  • requests should carry unique identifiers
  • request and response pairs should remain cryptographically linkable
  • exchange logs should preserve enough metadata to support evidence trails and troubleshooting

In X-Road environments, headers such as X-Road-Request-Hash or management correlation identifiers can be used to bind related events together across the exchange path.

Identifier and size considerations

Identifier constraints

Developers should treat member codes, subsystem codes, and service codes as controlled protocol identifiers, not free-form labels. X-Road identifiers have character restrictions, and values that include reserved characters can break routing or interoperability expectations.

At minimum, NRDEX implementation guidance should validate identifier formats centrally and prevent the use of values containing disallowed separator-style characters.

Message size limits

Protocol conformance alone is not enough for successful exchange. Implementers should also account for deployment-specific request and response size limits enforced by security servers, registration services, or supporting infrastructure.

For NRDEX documentation, this means payload-size expectations should be documented explicitly instead of assumed.

Implementation implications for NRDEX

For a national exchange layer, the protocol model implies that connected systems should be ready to:

  1. produce compliant SOAP or REST requests
  2. expose stable service identifiers
  3. publish WSDL or OpenAPI descriptions
  4. preserve request traceability
  5. handle exchange-layer error responses correctly
  6. respect identifier-format and payload-size constraints

Recommended NRDEX documentation checklist

  • service identifier format
  • required transport headers
  • request and response examples
  • versioning approach
  • interface description location
  • error model
  • traceability headers and audit linkage
  • identifier character restrictions
  • request and response size limits
  • security and certificate prerequisites

Reference note

This page is a working summary for NRDEX documentation and should be validated against the final protocol profile adopted for the Bangladesh implementation.