Documentation

NRDEX API and Integration Guidance

Service publication and consumer integration guidance for NRDEX members.

Overview

NRDEX is designed to expose governed machine-to-machine services between approved institutions. Providers publish services and consumers call them through approved exchange pathways.

Services are published inside a specific NRDEX instance, normally BD-TEST first and BD only after approval. Publication and consumption are separate controls: a provider can register a service without automatically allowing every member to consume it.

Service design expectations

  • Define each service around a clear institutional business purpose
  • Publish stable request and response contracts
  • Use versioned endpoints or versioned service identifiers
  • Document error responses and retry guidance
  • Avoid exposing internal implementation details

Integration model

  1. A provider defines a service and approval scope.
  2. The service is registered in the correct NRDEX instance.
  3. A consumer is authorized for the service.
  4. Traffic flows through the approved secure exchange path.

Service publish and consume rules

Provider publication rules

  • Register the provider's internal system as a Security Server client or subsystem.
  • Add the service description to the provider Security Server.
  • Publish REST services through an OpenAPI description and SOAP services through a WSDL description.
  • Define the service code, version, URL mapping, timeout, TLS expectation, and access conditions.
  • Grant access only to approved consumer members or subsystems.
  • Test the service first in BD-TEST; publish in BD only after governance, legal, and technical approval.

Consumer access rules

  • Register the consuming application as an approved subsystem.
  • Request access to the provider's service with the business purpose, expected traffic profile, and legal basis.
  • Configure the consumer application to call its own Security Server, not the provider backend directly.
  • Use the provider's published service identifier and follow the REST or SOAP protocol requirements.
  • Keep consumer logs, request identifiers, and support contacts ready for troubleshooting and audit.

API properties to publish

  • Service name
  • Service owner
  • NRDEX instance: BD-TEST or BD
  • Provider member code, subsystem code, service code, and version
  • Consumer eligibility
  • Legal basis or authorization condition
  • Protocol: REST or SOAP
  • Interface description: OpenAPI or WSDL URL/file
  • Backend URL mapping exposed through the provider Security Server
  • HTTP method and resource path for REST, or operation name for SOAP
  • Request schema
  • Response schema
  • Validation rules
  • Error codes
  • Rate or throughput constraints
  • Timeout and expected availability
  • Data classification and masking rules for test use
  • Support contact

Publishing a REST API

A REST API should be published as an X-Road REST service description on the provider Security Server.

  1. Prepare an OpenAPI 3 document that describes the public contract, not the internal implementation.
  2. Register the provider subsystem on the Security Server.
  3. Add the OpenAPI service description and map each published resource to the provider backend.
  4. Assign a stable service code and version, for example identity-verification and v1.
  5. Configure access rights for each approved consumer subsystem.
  6. Share the service identifier, OpenAPI description, request examples, error model, and support contact with approved consumers.

Consumers call the REST service through their own Security Server using the NRDEX/X-Road REST path and required headers, including X-Road-Client. The consumer application must not bypass NRDEX by calling the provider backend URL directly.

Publishing a SOAP API as a service

A SOAP API can be published as a service by exposing its WSDL through the provider Security Server.

  1. Prepare the WSDL and XSD files for the service contract.
  2. Register the provider subsystem on the Security Server.
  3. Add the WSDL service description to the Security Server and map operations to the provider SOAP backend.
  4. Confirm SOAP 1.1 compatibility and required X-Road SOAP headers.
  5. Define service code, service version, operation names, timeout, and error behavior.
  6. Grant access only to approved consumer subsystems.

Consumers call the SOAP service through their own Security Server using the published service identifier and SOAP headers for client, service, request identifier, user identifier where relevant, and protocol version. The provider backend remains behind the provider Security Server.

Example request contract

{
  "request_id": "req-2026-0001",
  "subject_nid": "1990123456789",
  "purpose_code": "identity_verification"
}

Example response contract

{
  "request_id": "req-2026-0001",
  "status": "verified",
  "matched": true,
  "timestamp": "2026-05-16T10:00:00Z"
}

Publishing rules and guidelines

No production service should be exposed through NRDEX unless its owning institution has approved the service definition, legal basis, and access conditions.

OpenAPI v3

For API services, use OpenAPI v3 to document the service contract.

Official protocol references