Skip to content

IOSetu API Guide

This guide provides comprehensive documentation for the IOSetu API, including endpoints, usage examples, and configuration.

Base URL

The API is served at http://localhost:8080 by default. You can view the interactive Swagger documentation at: http://localhost:8080/swagger/index.html

Endpoints

1. Health Check

  • Method: GET
  • Path: /health
  • Description: Returns 200 OK if the service is running.
curl http://localhost:8080/health

2. Parse AL3

  • Method: POST
  • Path: /v1/parse
  • Description: Parses an ACORD AL3 file and returns the structured JSON representation.
  • Headers:
    • Content-Type: application/octet-stream or text/plain
    • Accept: application/json (default), application/x-ndjson, text/csv, application/x-parquet
  • Response Metadata:
    • X-Processing-Time: Execution duration (e.g., 1.2ms)
    • X-IOSetu-Validation-Status: true/false

Example Request

curl -X POST \
  --data-binary "@sample.al3" \
  http://localhost:8080/v1/parse

Example Response (JSON)

{
  "data": {
    "fileId": "...",
    "policies": [...] 
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "processingTime": "1.234ms"
}

3. Validate AL3

  • Method: POST
  • Path: /v1/validate
  • Description: Validates an AL3 file without returning the full parsed structure. Faster if you only need validity checks.
curl -X POST --data-binary "@sample.al3" http://localhost:8080/v1/validate

4. Generate AL3

  • Method: POST
  • Path: /v1/generate
  • Description: Generates a valid AL3 file from structured JSON input. Performs strict validation against the schema.
  • Headers:
    • Content-Type: application/json
  • Response: JSON containing generated AL3 string and validation results.

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "policies": [{
      "code": "1MHG",
      "dataElements": {
        "Transaction Date": "20240115"
      },
      "children": [...]
    }]
  }' \
  http://localhost:8080/v1/generate

Example Response

{
  "data": "1MHG... (AL3 content)",
  "validation": {
    "valid": true,
    "errors": []
  },
  "metadata": {
    "sizeBytes": 1024,
    "groupCount": 15
  },
  "processingTime": "1.5ms"
}

Configuration

Telemetry (OpenTelemetry)

Tracing is disabled by default to avoid connection errors during local development.

  • Enable: Set IOSETU_TELEMETRY_ENABLED=true
  • Endpoint: Defaults to localhost:4318. Configure with OTEL_EXPORTER_OTLP_ENDPOINT.

Server Port

  • Default: 8080
  • Env Var: IOSETU_PORT (e.g., export IOSETU_PORT=9090)

Running IOSetu

IOSetu Cloud (AWS Marketplace)

Pull and run the container from AWS Marketplace:

docker pull priyaiosystems/iosetu:latest
docker run -d -p 8080:8080 --name iosetu priyaiosystems/iosetu:latest

The API will be available at http://localhost:8080.

For production deployment on AWS, see the AWS Integration Guide