2927013a6d
- Updated `.env` and added `.env.test` for environment variables. - Introduced API documentation in `API_DOCUMENTATION.md`. - Added authentication setup guide in `AUTHENTICATION_SETUP.md`. - Implemented user authentication with JWT and email verification. - Created new routes for user management and form submissions. - Added middleware for API key authentication and error handling. - Set up Redis for rate limiting and notifications. - Removed obsolete files and configurations related to the previous Rust implementation.
99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
# Formies API Documentation (v1)
|
|
|
|
This document provides instructions on how to use the Formies API to access your forms and submission data programmatically.
|
|
|
|
## Authentication
|
|
|
|
All API requests must be authenticated using an API Key.
|
|
|
|
1. **Generate an API Key**: You can generate and manage your API keys from your user dashboard under the "API Keys" section.
|
|
2. **Pass the API Key**: The API key must be included in the `Authorization` header of your HTTP requests, using the `Bearer` scheme.
|
|
|
|
Example:
|
|
|
|
```
|
|
Authorization: Bearer YOUR_FULL_API_KEY_HERE
|
|
```
|
|
|
|
Replace `YOUR_FULL_API_KEY_HERE` with the actual API key you generated (e.g., `fsk_xxxxxxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy`).
|
|
|
|
If authentication fails (e.g., missing key, invalid key, expired key), the API will respond with a `401 Unauthorized` or `403 Forbidden` status code and a JSON error message.
|
|
|
|
## Endpoints
|
|
|
|
All API endpoints are prefixed with `/api/v1`.
|
|
|
|
### 1. List Your Forms
|
|
|
|
- **Endpoint**: `GET /api/v1/forms`
|
|
- **Method**: `GET`
|
|
- **Authentication**: Required (Bearer Token)
|
|
- **Description**: Retrieves a list of all forms owned by the authenticated user.
|
|
- **Successful Response (200 OK)**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"forms": [
|
|
{
|
|
"uuid": "form-uuid-123",
|
|
"name": "My Contact Form",
|
|
"created_at": "2023-10-26T10:00:00.000Z",
|
|
"is_archived": false,
|
|
"submission_count": 150
|
|
}
|
|
// ... other forms
|
|
]
|
|
}
|
|
```
|
|
- **Error Responses**:
|
|
- `401 Unauthorized`: Authentication failed.
|
|
- `500 Internal Server Error`: If there was an issue fetching the forms.
|
|
|
|
### 2. List Submissions for a Form
|
|
|
|
- **Endpoint**: `GET /api/v1/forms/:formUuid/submissions`
|
|
- **Method**: `GET`
|
|
- **Authentication**: Required (Bearer Token)
|
|
- **Path Parameters**:
|
|
- `formUuid` (string, required): The UUID of the form for which to retrieve submissions.
|
|
- **Query Parameters (for pagination)**:
|
|
- `page` (integer, optional, default: `1`): The page number of submissions to retrieve.
|
|
- `limit` (integer, optional, default: `25`): The number of submissions to retrieve per page.
|
|
- **Description**: Retrieves a paginated list of submissions for a specific form owned by the authenticated user.
|
|
- **Successful Response (200 OK)**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"formName": "My Contact Form",
|
|
"formUuid": "form-uuid-123",
|
|
"pagination": {
|
|
"currentPage": 1,
|
|
"totalPages": 3,
|
|
"totalSubmissions": 65,
|
|
"limit": 25,
|
|
"perPage": 25,
|
|
"count": 25
|
|
},
|
|
"submissions": [
|
|
{
|
|
"id": 1,
|
|
"data": { "email": "test@example.com", "message": "Hello!" },
|
|
"ip_address": "123.123.123.123",
|
|
"submitted_at": "2023-10-27T14:30:00.000Z"
|
|
}
|
|
// ... other submissions for the current page
|
|
]
|
|
}
|
|
```
|
|
- **Error Responses**:
|
|
- `401 Unauthorized`: Authentication failed.
|
|
- `403 Forbidden`: If the authenticated user does not own the specified form.
|
|
- `404 Not Found`: If the specified `formUuid` does not exist.
|
|
- `500 Internal Server Error`: If there was an issue fetching the submissions.
|
|
|
|
## General Notes
|
|
|
|
- All API responses are in JSON format.
|
|
- Successful responses will generally include a `success: true` field.
|
|
- Error responses will include `success: false` and an `error` field (string or object) with details.
|