6 Examples

6.1 Scope: The "God Service" vs. Single Capability

The Rule: A service must own a single domain of logic. If you cannot describe the service function without using the word "and" (e.g., "Login and Tax"), the boundary is too broad.

BAD: The Ambiguous Monolith

• Problem: Multiple, unrelated domains mixed in one endpoint (e.g., mixing user logic with business processing).
• AI Consequence: The Agent cannot determine the scope or intent of the service, leading to hallucination risks.

// POST /api/handleStuff
// Description: Missing.
{
  "action": "register_and_notify", // Mixing logic
  "data": { ... }, // Generic object with no schema
  "misc_flag": true
}

GOOD: The Bounded Context

• Solution: One purpose per API. The service handles exactly one coherent capability.
• AI Benefit: The agent can instantly identify which endpoint handles a specific life event.

// POST /benefits/unemployment/claims
{
  "openapi": "3.1.0",
  "paths": {
    "/claims": {
      "post": {
        "summary": "Submit Unemployment Claim",
        "description": "Creates a new claim for a specific citizen context.",
        "operationId": "submitClaim",
        "tags": ["Unemployment"]
      }
    }
  }
}

6.2 Data Models: Vague Inputs vs. Explicit Types

The Rule: Architects must strictly avoid free-text string fields for data that has a finite set of valid values.

BAD: The "Stringly Typed" Interface

• Problem: Inputs are vague with no clear patterns. Almost everything is optional (nillable).
• AI Consequence: Leads to "hallucinations" where the AI invents plausible but non-existent status codes (e.g., "Partially_OK") because the rules aren't strict.

{
  "status": "string", // Could be anything?
  "date": "string",   // DD/MM/YYYY? YYYY-MM-DD?
  "file": "string"    // Base64? URL? S3 bucket?
}

GOOD: Deterministic Types & Enums

• Solution: Define strict types, enums, patterns, and required fields using OpenAPI 3.1 standards.
• AI Benefit: Reduces the "search space" for the agent, making invalid states unrepresentable.

{
  "properties": {
    "status": {
      "type": "string",
      "enum": ["PENDING", "APPROVED", "REJECTED"] // Strict bounds
    },
    "submissionDate": {
      "type": "string",
      "format": "date-time" // ISO 8601 enforced
    },
    "evidenceDocument": {
      "type": "string",
      "contentMediaType": "application/pdf", // Explicit MIME type
      "format": "binary"
    }
  },
  "required": ["status", "submissionDate"]
}

6.3 Error Handling: Ambiguity vs. Structured Logic

The Rule: When an AI agent encounters a roadblock, the system must provide explicit, machine-readable instructions on how to resolve it.

BAD: The "False Success"

• Problem: Responses mix success data and error fields. The HTTP status is 200 OK, but the body contains an error.
• AI Consequence: The automation fails to detect the failure or hallucinates a workaround because it lacks structured feedback.

// HTTP 200 OK (Misleading Status)
{
  "success": false,
  "errorMsg": "Something went wrong", // Vague text
  "data": null
}

GOOD: RFC 9457 Structured Errors

• Solution: Always return standard status codes and structured Problem Details (RFC 9457).
• AI Benefit: The agent can parse the error logic programmatically and apply a specific fix (e.g., reformatting a phone number).

// HTTP 400 Bad Request
{
  "type": "https://api.gov/errors/invalid-format",
  "title": "Invalid Identification Number",
  "detail": "The ID number must be exactly 11 digits.",
  "instance": "/claims/12345/id",
  "invalid-params": [
    {
      "name": "national_id",
      "reason": "must match regex ^[0-9]{11}$"
    }
  ]
}

6.4 Naming: Inconsistency vs. Documentation

The Rule: The API Contract is the primary product interface for machine agents.

BAD: The Linguistic Mix

• Problem: Naming is inconsistent (mixing local language + English, different casing styles).
• AI Consequence: Confusing to map; requires "guessing" the intent of fields.

{
  "Synniaeg": "1990-01-01", // Local Language mixed in
  "firstName": "John",      // English camelCase
  "LAST_NAME": "DOE"        // English CONSTANT_CASE
}

GOOD: Consistent Semantics

• Solution: Use one language and style. Include short descriptions for every field.
• AI Benefit: Ensures the machine agent can distinguish between unrelated tasks despite underlying complexity

{
  "properties": {
    "dateOfBirth": {
      "type": "string",
      "format": "date",
      "description": "The official date of birth as recorded in the population registry."
    },
    "firstName": {
      "type": "string",
      "description": "Given name."
    },
    "lastName": {
      "type": "string",
      "description": "Family name."
    }
  }
}