# API Documentation Structure

This directory contains the API definitions for the FMEA system, organized by version and resource.

## Directory Pattern

All endpoints MUST follow this strictly nested directory structure:

```
endpoints/
  ├── v1/
  │   └── {resource}/
  │       ├── core.json       # Basic CRUD operations
  │       ├── {feature}.json  # Feature-specific endpoints (e.g., export.json)
  │       └── ...
  └── v2/
      └── {resource}/
          └── ...
```

### Classification Rules

To prevent ambiguity, follow these classification principles:

- **Domain Specific**: If an endpoint operates *within the context* of a specific resource (e.g., "Export THIS resource's sub-data"), place it under that resource's directory.
    - Example: `/api/v2/main-resources/{id}/sub-feature` -> `endpoints/v2/main-resources/sub-feature.json`

- **Global / Utility**: If an endpoint is a generic utility or operates independently of other resources (e.g., "Process ANY file"), create a dedicated top-level resource directory.
    - Example: `/api/v2/standalone-feature` -> `endpoints/v2/standalone-feature/core.json`

### Rules

1.  **Directory Required**: Every resource (e.g., `projects`, `users`) MUST be a directory, even if it only contains one file.
2.  **Core File**: The main file for a resource should be named `core.json`. This typically contains the basic CRUD operations.
3.  **Feature Files**: Distinct sub-features should be separated into their own JSON files with descriptive names (e.g., `excel.json`, `lifecycle.json`).
4.  **JSON Structure**: Each file must contain a valid JSON object with:
    - `category`: String (Resource category name)
    - `version`: String ("v1" or "v2")
    - `description`: String (Resource description)
    - `endpoints`: Array of endpoint objects. Each object MUST contain:
        - `path`: String (URI path)
        - `method`: String (HTTP method)
        - `summary`: String (Concise "Action + Object" format. e.g., "Create new Project")
        - `description`: String (Detailed description with synonyms, intent, and context for AI search)
        - `tags`: Array of Strings
        - `operationId`: String (Unique identifier)
        - `parameters`: Array (Optional parameters)
        - `responses`: Object (Response definitions)
    - `x-dependency-warning`: String (Optional). **URGENT**: When an endpoint depends on a prior initiation step (like file upload), this field MUST be included. It should state "REQUIRES PRIOR {ACTION} via [{METHOD} {PATH}]".

### Example

### Example

```
endpoints/v1/projects/
  ├── core.json
  ├── lifecycle.json
  ├── data.json
  └── recommendations.json
```

## Search Optimization (SEO) & AI Context

To ensure high accuracy in AI semantic search and RAG contexts, descriptions MUST follow these rules:

1.  **Include Synonyms & Intent**: Incorporate alternative terms and user intent.
    -   *Bad*: "Log out user."
    -   *Good*: "Terminates the user session and invalidates the refresh token (Log out / Sign out)."
2.  **Contextual Clarity**: Explain *why* and *when* to use this endpoint.
    -   **Length Limit**: Keep descriptions between **50 and 150 words**. Explain logic clearly but avoid excessive verbosity.
3.  **Keywords**: Naturally include terms likely to be used in natural language queries (e.g., "Excel export", "bulk upload", "reset password").

## Advanced Patterns & Dependencies

To ensure AI agents correctly navigate complex workflows, strict patterns for dependency management are enforced.

### 1. Documentation Standard: `x-dependency-warning`

When an endpoint depends on a prior initiation step (e.g., file upload, login), the definition MUST include the `x-dependency-warning` field.

-   **Field**: `x-dependency-warning`
-   **Value Format**: `"REQUIRES PRIOR {ACTION} via [{METHOD} {PATH}]. {CONTEXT}"`
-   **Example**:
    ```json
    "x-dependency-warning": "REQUIRES PRIOR FILE UPLOAD via [POST /api/v2/files]. The {uuid} parameter is the file ID returned by the upload endpoint."
    ```

### 2. Workflow Pattern: File Upload & Processing

This is the canonical pattern for handling file-based operations in this API.

**The Workflow:**
1.  **Initiator**: Client uploads a file via `POST /api/v2/files` -> Returns `{uuid}`.
2.  **Consumer**: Client calls processing endpoints (e.g., `GET /api/v2/excel/{uuid}`) using that `{uuid}`.

**AI Operational Protocol:**
When this pattern is identified (via `x-dependency-warning` or path analysis), the AI MUST:

1.  **Stop & Check**: If the user requests a "Consumer" action, verify if a file `uuid` is available in context.
2.  **Propose Initiator**: If no `uuid` exists, explicitly propose the file upload step first.
3.  **Auto-Chain**: Once the upload is complete, capture the `uuid` and automatically apply it to subsequent steps without asking the user.

### 3. Identification Criteria

Use these signals to identify dependency roles if `x-dependency-warning` is missing:

| Role | Signals |
| :--- | :--- |
| **Initiator** | Path ends in `/files`, `/upload`; Method is `POST`; Returns an ID. |
| **Consumer** | Path contains `{uuid}`; Logic involves parsing/extracting; Does *not* create `{uuid}` resource. |
