72 lines
2.6 KiB
Markdown
72 lines
2.6 KiB
Markdown
# 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.
|