# Form Utility API Documentation

## Overview
This document provides a quick reference for the **Form Utility** backend API endpoints that are intended for consumption by the frontend. All endpoints are prefixed with the base URL of the deployed service (e.g., `https://api.example.com`).

---

## Endpoints

| Method | Path | Description | Request Body | Success Response | Notes |
|--------|------|-------------|--------------|------------------|-------|
| **POST** | `/form/create-or-update` | Create a new form or update an existing one. If `id` is omitted, a new form is created; otherwise the specified form is updated. | `CreateUpdateDto` (JSON) | `{ "id": "string", "name": "string", "field": { ... } }` | Returns the created/updated form object. |
| **GET** | `/form` | Retrieve a list of all forms. | _None_ | `Form[]` (array of form objects) | Pagination is not implemented yet. |
| **PATCH** | `/form/:id/fields/:fieldId` | Update a specific field within a form. | `UpdateFieldDto` (JSON) | Updated field object | `:id` – Form identifier, `:fieldId` – Field identifier. |
| **DELETE** | `/form/:id/fields/:fieldId` | Delete a specific field from a form. | _None_ | `{ "deleted": true }` | Returns a simple confirmation object. |
| **GET** | `/` (root) | Health‑check / greeting endpoint used by the default NestJS scaffold. | _None_ | `"Hello World!"` (string) | Useful for quick service availability checks. |

---

## DTO Schemas (TypeScript Interfaces)

### `CreateUpdateDto`
```ts
export class CreateUpdateDto {
  /** Form ID — omit to create a new form */
  id?: string;

  /** Human‑readable name of the form */
  name?: string;

  /** Optional initial field definition */
  field?: CreateFieldDto;
}
```

### `UpdateFieldDto`
```ts
export class UpdateFieldDto {
  /** New label for the field */
  label?: string;

  /** Updated value type (e.g., 'text', 'number') */
  type?: string;

  /** Validation rules, if any */
  validation?: Record<string, any>;
}
```

---

## Usage Example (Fetch API)
```js
// Create a new form
await fetch('https://api.example.com/form/create-or-update', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Customer Survey' })
});

// Get all forms
const forms = await fetch('https://api.example.com/form').then(r => r.json());
```

---

## Notes for Frontend Developers
- All endpoints return JSON payloads.
- No authentication is currently enforced; add JWT headers when the auth layer is enabled.
- Errors are returned with standard NestJS error format (`statusCode`, `message`, `error`).
- The API follows conventional REST semantics; feel free to extend with pagination or filtering as needed.