# 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."
    }
  }
}
```