Skip to content

Real-Time API Integration Guide

This guide describes how to integrate the Integra API for synchronous, real-time AL3 translation in your applications.

When to Use Real-Time API

  • Web Applications: Provide instant feedback to users uploading AL3 files.
  • Microservices: Integrate AL3 parsing into an existing policy administration workflow.
  • Interactive Tools: Single-file inspection or editing.

Core Endpoint: /v1/parse

Request Specification

  • Method: POST
  • URL: http://<integra-host>:8080/v1/parse
  • Body: Raw binary AL3 content (or text/plain).
  • Headers:
    • Content-Type: application/octet-stream (recommended)
    • Accept: application/json

Response Specification

  • Status 200: Successful parse (note: validation errors may still exist, check validation object).
  • Status 400: Bad Request (empty body, invalid headers).
  • Status 422: Validation failed (if severe).
  • Status 500: Internal server error.

Client Examples

Python (Requests)

import requests

def parse_al3(file_path):
    with open(file_path, 'rb') as f:
        data = f.read()

    try:
        response = requests.post(
            'http://localhost:8080/v1/parse',
            data=data,
            headers={'Content-Type': 'application/octet-stream'},
            timeout=5  # Set appropriate timeout
        )
        response.raise_for_status()

        result = response.json()
        if not result['validation']['valid']:
            print("Warning: Validation errors found")
            for err in result['validation']['errors']:
                print(f"- {err}")

        return result['data']

    except requests.exceptions.RequestException as e:
        print(f"API Error: {e}")
        return None

Node.js (Axios)

const axios = require('axios');
const fs = require('fs');

async function parseAL3(filePath) {
  try {
    const fileData = fs.readFileSync(filePath);

    const response = await axios.post(
      'http://localhost:8080/v1/parse', 
      fileData,
      {
        headers: { 'Content-Type': 'application/octet-stream' },
        maxContentLength: Infinity,
        maxBodyLength: Infinity
      }
    );

    const { data, validation } = response.data;

    if (!validation.valid) {
      console.warn('Validation errors:', validation.errors);
    }

    return data;
  } catch (error) {
    console.error('Parsing failed:', error.message);
    throw error;
  }
}

Error Handling

Status Meaning Action
200 Success Check validation.valid flag for non-fatal issues.
400 Bad Request Check request body is not empty and headers are correct.
422 Unprocessable The file is not a valid AL3 (missing 1MHG header, etc.).
500 Server Error Retry with backoff. Report issue to support if persistent.
503 Service Unavailable Integra is overloaded or starting up. Retry.

Performance Tips

  1. Keep Connections Alive: Use a persistent HTTP client session (Connection Pooling).
  2. Accept Gzip: Send Accept-Encoding: gzip to reduce response transfer time for large JSONs.
  3. Use NDJSON: If you don't need the full object in memory, request application/x-ndjson to stream the response.