API Reference

Overview

The Fintegrator TODS REST API provides programmatic access to field mapping data, application metadata, and system health. All endpoints use JSON.

Base URL: https://todsdev.fintegrator.eu/api

Interactive docs (Swagger): https://todsdev.fintegrator.eu/api/swagger

Authentication: API requests require a valid Keycloak session token (Bearer). Obtain a token via the standard OAuth 2.0 client-credentials or authorization-code flow against the Keycloak realm configured for this deployment.

Endpoints

Health

GET /health

Liveness probe — checks application process only, no database dependency.

curl https://todsdev.fintegrator.eu/api/health

Response (HTTP 200):

Healthy

GET /health/ready

Readiness probe — includes database connectivity check.

curl https://todsdev.fintegrator.eu/api/health/ready

Response (HTTP 200 — healthy):

Healthy

Response (HTTP 503 — database unavailable):

{
  "status": "Unhealthy",
  "results": {
    "database": {
      "status": "Unhealthy",
      "description": "Unable to connect to database"
    }
  }
}

Applications

GET /applications

Returns all T24 application names registered for replication.

curl https://todsdev.fintegrator.eu/api/applications

Response (HTTP 200):

["AA.ACCOUNT.DETAILS", "ABBREVIATION", "ACCOUNT", "CUSTOMER", "FUNDS.TRANSFER", ...]

The list contains 150+ applications. Results are cached for 5 minutes.

Field Mappings

GET /mappings

Returns all field mappings for all applications (~10,000+ records, ~5 MB). Prefer /mappings/{applicationName} for specific use cases.

curl https://todsdev.fintegrator.eu/api/mappings

GET /mappings/{applicationName}

Returns field mappings for a single T24 application.

curl https://todsdev.fintegrator.eu/api/mappings/CUSTOMER

Response (HTTP 200):

[
  {
    "id": 0,
    "t24Application": "CUSTOMER",
    "fieldNumber": 0,
    "fieldTag": "c0",
    "fieldName": "CUSTOMER.CODE",
    "fieldType": "D",
    "fieldValidation": "IN2CUS&&&&&&DICT",
    "fieldFormat": "10R",
    "fieldTypeSql": "int",
    "fieldIndexType": -1,
    "multiValue": "S",
    "multiValueOrder": 0,
    "mapName": "CustomerCode",
    "mapGroup": null,
    "mapDescription": "Customer unique identifier",
    "helpText": "Specifies the unique customer code...",
    "timeStamp": "2024-05-14T20:00:00",
    "userStamp": "demouser"
  }
]

Response schema:

Field Type Description
id number Unique mapping ID
t24Application string T24 application name
fieldNumber number T24 field number
fieldTag string Field tag (e.g. c0)
fieldName string T24 field name
fieldType string D = data field
fieldValidation string T24 validation rules
fieldFormat string T24 format (e.g. 35L, 10R)
fieldTypeSql string|null SQL Server data type
fieldIndexType number 0 = clustered, 1 = non-clustered, -1 = none
multiValue string|null S = single value, M = multi-value
multiValueOrder number Ordering within a multi-value group
mapName string|null ODS column name
mapGroup string|null Multi-value group name
mapDescription string|null Business description
helpText string T24 help text (from XML)
timeStamp string Last modified (ISO 8601)
userStamp string|null Last modifier username

Error responses:

HTTP 404 — application not found:

{ "error": "Application 'INVALID_APP' not found" }

PUT /mappings/{id}

Updates an existing field mapping. Calls mfe.spUpdateField in the database.

Path parameter: id — mapping ID from the GET response.

curl -X PUT https://todsdev.fintegrator.eu/api/mappings/0 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "t24Application": "CUSTOMER",
    "fieldTag": "c0",
    "fieldName": "CUSTOMER.CODE",
    "fieldTypeSql": "int",
    "fieldIndexType": -1,
    "multiValue": "S",
    "multiValueOrder": 0,
    "mapName": "CustomerCode",
    "mapGroup": null,
    "mapDescription": "Customer unique identifier"
  }'

Response: HTTP 204 No Content on success.

Request body schema:

Field Type Required Description
t24Application string Yes T24 application name
fieldTag string Yes Field tag (e.g. c0)
fieldName string Yes T24 field name
fieldTypeSql string Yes SQL Server data type
fieldIndexType number Yes 0 / 1 / -1
multiValue string Yes S or M
multiValueOrder number|null No Multi-value sequence
mapName string Yes ODS column name
mapGroup string|null No Multi-value group
mapDescription string|null No Business description

Error responses:

HTTP 400 — validation error:

{ "errors": { "fieldTypeSql": ["The fieldTypeSql field is required."] } }

HTTP 404 — mapping not found:

{ "error": "Mapping with ID 999 not found" }

Error Format

All error responses follow RFC 7807 Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "fieldName": ["Error message"] },
  "traceId": "00-abc123-def456-00"
}

HTTP status codes:

Code Meaning
200 Request successful
204 Update successful, no response body
400 Validation error or malformed JSON
401 Missing or invalid authentication token
404 Resource not found
500 Server or database error
503 Service not ready (database offline)

Code Examples

JavaScript

const BASE = "https://todsdev.fintegrator.eu/api";
const TOKEN = "<your-bearer-token>";

// Get all applications
const apps = await fetch(`${BASE}/applications`, {
  headers: { Authorization: `Bearer ${TOKEN}` }
}).then(r => r.json());

// Get CUSTOMER field mappings
const mappings = await fetch(`${BASE}/mappings/CUSTOMER`, {
  headers: { Authorization: `Bearer ${TOKEN}` }
}).then(r => r.json());

// Update a field mapping
await fetch(`${BASE}/mappings/0`, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`
  },
  body: JSON.stringify({
    t24Application: "CUSTOMER",
    fieldTag: "c0",
    fieldName: "CUSTOMER.CODE",
    fieldTypeSql: "int",
    fieldIndexType: -1,
    multiValue: "S",
    mapName: "CustomerCode"
  })
});

C#

using System.Net.Http.Json;

var client = new HttpClient { BaseAddress = new Uri("https://todsdev.fintegrator.eu/api/") };
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "<token>");

var apps     = await client.GetFromJsonAsync<string[]>("applications");
var mappings = await client.GetFromJsonAsync<List<T24FieldMapping>>("mappings/CUSTOMER");

var response = await client.PutAsJsonAsync("mappings/0", new {
    t24Application = "CUSTOMER",
    fieldTag       = "c0",
    fieldName      = "CUSTOMER.CODE",
    fieldTypeSql   = "int",
    fieldIndexType = -1,
    multiValue     = "S",
    mapName        = "CustomerCode"
});

Python

import requests

BASE  = "https://todsdev.fintegrator.eu/api"
HEADERS = {"Authorization": "Bearer <token>"}

apps     = requests.get(f"{BASE}/applications", headers=HEADERS).json()
mappings = requests.get(f"{BASE}/mappings/CUSTOMER", headers=HEADERS).json()

r = requests.put(
    f"{BASE}/mappings/0",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "t24Application": "CUSTOMER",
        "fieldTag": "c0",
        "fieldName": "CUSTOMER.CODE",
        "fieldTypeSql": "int",
        "fieldIndexType": -1,
        "multiValue": "S",
        "mapName": "CustomerCode"
    }
)
assert r.status_code == 204

PowerShell

$base    = "https://todsdev.fintegrator.eu/api"
$headers = @{ Authorization = "Bearer <token>" }

$apps     = Invoke-RestMethod "$base/applications" -Headers $headers
$mappings = Invoke-RestMethod "$base/mappings/CUSTOMER" -Headers $headers

Invoke-RestMethod "$base/mappings/0" -Method PUT -Headers $headers `
    -ContentType "application/json" `
    -Body (@{
        t24Application = "CUSTOMER"; fieldTag = "c0"; fieldName = "CUSTOMER.CODE"
        fieldTypeSql   = "int"; fieldIndexType = -1; multiValue = "S"
        mapName        = "CustomerCode"
    } | ConvertTo-Json)

Performance Reference

Measured on a standard cluster deployment:

Endpoint Typical response
GET /health ~2 ms
GET /health/ready ~2 ms
GET /applications ~6 ms
GET /mappings/{app} ~5 ms
GET /mappings (all) ~80–120 ms
PUT /mappings/{id} ~10 ms