Binding
Concrete Specification
Prerequisites
This protocol uses HTTPS (TLS 1.2 or higher) and communicates via RESTful HTTP request/response.
Endpoints: HTTP methods (GET, POST, PUT, DELETE) are used against specified URIs.
Data Format: Request and response bodies use JSON format.
Field Definitions
For each field used in this binding, the following information is provided:
Field Name: Name used within the protocol
Type: Data type (e.g., integer, string)
Requirement:
R = Required
C = Conditional
O = Optional
Request: Used in request messages
Response: Used in response messages
Description: Meaning and usage of the field
Header Field Definitions
During communication, the following header fields are required from the client. Any headers not listed below are optional and are not processed by the Web API Transfer Module.
API-Key
String
C
✔
✔
Specifies the API key issued per client application.
Authorization
String
R
✔
Specifies the access token. Example: Bearer
X-TrackingID
String
C
✔
✔
✔
Specifies a unique ID used for request tracing. If not provided by the client, the Web API Transfer Module automatically generates a UUID. Depending on the integrated function, this field may become mandatory (e.g., when integrating with clearing and payment services).
X-ODS-xxx
String
O
✔
✔
Extension header used for internal ODS control. For example, it may be used for log-based consistency verification in a clearing and payment service (a type of Dataspace Complementary Service, DCS). Replace "xxx" with an arbitrary identifier (e.g., X-ODS-UserId).
Payload Field Definitions
The Web API Transfer Module adopts a transparent API gateway approach. Since the payload structure depends on the API specification provided by the Data Provider, refer to the relevant Data Provider system specification for detailed payload definitions.
For error responses, the following JSON payload is returned:
code
String
[prefix] {Error Status}
Error code including a prefix. Prefix values are as follows: - dataspace: Error occurred within the Web API Transfer Module - auth: Authentication or authorization-related error
message
String
{Error Message}
Detailed error message
detail
String
{Timestamp}
Timestamp in ISO 8601 UTC format
Example:
Functional Description
The Web API Transfer Module adopts a transparent API gateway approach and is limited to routing functionality. It does not provide payload parsing or model transformation capabilities. The Web API Transfer Module intermediates communication between Data Consumer applications and Data Provider systems and provides Policy Enforcement Point (PEP) functionality for token validation and authorization control in coordination with the Identity Component.
The Transaction Layer provides the following functions:
Routing
Provides routing functionality as a transparent API gateway.
Routing rules are registered as "routes" to mediate between Data Consumers and Data Providers. Each route forwards requests to the target system API based on request conditions (path, method, headers, etc.). By modifying route configurations, destinations and conditions can be dynamically added or updated. During routing, the Web API Transfer Module performs necessary processing (e.g., generating a UUID if X-TrackingID is not included in the request header, rewriting headers, etc.).
Authentication Control
Performs client authentication.
Two authentication mechanisms are supported: - API Key Authentication: Validates the "API-Key" request header within the Web API Transfer Module. - OAuth 2.0 / OpenID Connect Token Introspection: Validates the access token in the "Authorization" request header in coordination with the Identity & Trust（L3）. If validation fails or the token is expired, the module returns an HTTP 401 Unauthorized response with a JSON error payload. By separating authentication control from business logic, responsibilities are clearly defined, maintainability is improved, and changes to authentication mechanisms have minimal impact on the gateway.
Authorization Control
Operates as a Policy Enforcement Point (PEP).
As a PEP, it coordinates with the Identity & Trust（L3） acting as the Policy Decision Point (PDP) to perform authorization control. Integration with the authorization function (OpenFGA) is achieved via the AuthZEN API. Since authorization requirements vary by use case, authorization control can be enabled or disabled by configuration.
Logging
Outputs logs required for ODS platform operation and maintenance.
Logs include routing information, traffic information, and data required for integration with Dataspace Complementary Services (DCS). Logged information includes: Request phase: request source information, request destination information, API information, request received time, request sent time, X-TrackingID, X-ODS-xxx headers. Response phase: response received time, response sent time, X-TrackingID, status code.
Route Persistence
Persists route information required for routing.
- Persist route information in a database to prevent loss upon restart. Persisted routes are loaded when the Web API Transfer Module starts. - Manage route information per use case. When multiple use cases share a single database instance, routes are separated using database schemas. The Web API Transfer Module specifies the schema in the database connection configuration to retrieve the appropriate route information.
File Transfer
Supports file transmission through the Web API Transfer Module.
- File Retrieval: Retrieves file-based data (typically several MB in size) from a connected system via the Web API Transfer Module. - File Transmission: Transfers file-based data (typically several MB in size) to a connected system via the Web API Transfer Module.
Portability
Operates on a container platform.
Designed to run on container infrastructure and does not depend on specific cloud services.
Sequence Diagram
Sequence Description
1
The client (Data Consumer) sends an HTTP request to the Web API Transfer Module to execute a Data Provider API.
2
The Web API Transfer Module validates the API key. If valid, it sends an HTTP request to the token introspection endpoint of the Identity Component to verify the access token. If X-TrackingID is not included in the request header, a new UUID is generated.
3
The Identity Component validates the token and returns the validation result (e.g., validity, scope).
4
The Web API Transfer Module sends an HTTP request to the authorization check endpoint to verify whether the requested operation is permitted.
5
The Identity Component evaluates access rights based on policy and returns the authorization result.
6
If authentication and authorization succeed, the Web API Transfer Module forwards the HTTP request to the Data Provider API endpoint.
7
The Data Provider processes the request and returns the result to the Web API Transfer Module.
8
The Web API Transfer Module transparently returns the API result to the client.
Last updated