Skip to content

Beautiful Open-Source Form Builder

Enhance API documentation and routing for workspace forms

Julien Nahum424afa349a98
diff --git a/.cursor/rules/docs.mdc b/.cursor/rules/docs.mdc
index 491e8878a..72c78b7ed 100644
--- a/.cursor/rules/docs.mdc
+++ b/.cursor/rules/docs.mdc
@@ -1,8 +1,9 @@
---
-description:
+description:
globs: docs/**/*.*
alwaysApply: false
---
+
# Mintlify technical writing assistant
You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
@@ -10,6 +11,7 @@ You are an AI writing assistant specialized in creating exceptional technical do
## Core writing principles
### Language and style requirements
+
- Use clear, direct language appropriate for technical audiences
- Write in second person ("you") for instructions and procedures
- Use active voice over passive voice
@@ -19,6 +21,7 @@ You are an AI writing assistant specialized in creating exceptional technical do
- Use parallel structure in lists, headings, and procedures
### Content organization standards
+
- Lead with the most important information (inverted pyramid structure)
- Use progressive disclosure: basic concepts before advanced ones
- Break complex procedures into numbered steps
@@ -28,6 +31,7 @@ You are an AI writing assistant specialized in creating exceptional technical do
- Use descriptive, keyword-rich headings for navigation and SEO
### User-centered approach
+
- Focus on user goals and outcomes rather than system features
- Anticipate common questions and address them proactively
- Include troubleshooting for likely failure points
@@ -73,11 +77,11 @@ Positive confirmations, successful completions, or achievement indicators
```javascript config.js
const apiConfig = {
-baseURL: 'https://api.example.com',
-timeout: 5000,
-headers: {
- 'Authorization': `Bearer ${process.env.API_TOKEN}`
-}
+ baseURL: "https://api.example.com",
+ timeout: 5000,
+ headers: {
+ Authorization: `Bearer ${process.env.API_TOKEN}`,
+ },
};
```
@@ -92,7 +96,7 @@ const response = await fetch('/api/endpoint', {
```python Python
import requests
-response = requests.get('/api/endpoint',
+response = requests.get('/api/endpoint',
headers={'Authorization': f'Bearer {api_key}'})
```
@@ -100,6 +104,7 @@ response = requests.get('/api/endpoint',
curl -X GET '/api/endpoint' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
+
</CodeGroup>
#### Request/Response examples
@@ -293,9 +298,10 @@ API
- Improved error messages with actionable suggestions
## Bug fixes
+
- Fixed pagination issue with large datasets
- Resolved authentication timeout problems
-</Update>
+ </Update>
## Required page structure
@@ -311,6 +317,7 @@ description: "Concise description explaining page purpose and value"
## Content quality standards
### Code examples requirements
+
- Always include complete, runnable examples that users can copy and execute
- Show proper error handling and edge case management
- Use realistic data instead of placeholder values
@@ -320,6 +327,7 @@ description: "Concise description explaining page purpose and value"
- Add explanatory comments for complex logic
### API documentation requirements
+
- Document all parameters including optional ones with clear descriptions
- Show both success and error response examples with realistic data
- Include rate limiting information with specific limits
@@ -327,7 +335,36 @@ description: "Concise description explaining page purpose and value"
- Explain all HTTP status codes and error handling
- Cover complete request/response cycles
+### Adding new API endpoints
+
+When adding a new API endpoint to the documentation, you must update multiple files to ensure consistency across the documentation system:
+
+1. **Create or update the MDX documentation file** (`docs/api-reference/{category}/{endpoint-name}.mdx`):
+ - Create a new MDX file in the appropriate category directory (e.g., `forms/`, `workspaces/`, `submissions/`)
+ - Include the OpenAPI reference in the frontmatter: `openapi: {method} {path}`
+ - Follow the standard structure: Authentication & Scope, Request, Response sections
+ - Include all path parameters, query parameters, and request/response examples
+
+2. **Update the navigation** (`docs/docs.json`):
+ - Add the new page path to the appropriate group in the API Reference section
+ - Maintain logical ordering (CRUD operations: list, create, get, update, delete)
+ - Place deprecated endpoints after their replacements
+
+3. **Update the OpenAPI specification** (`docs/api-reference/openapi.yaml`):
+ - Add the endpoint definition under the `paths` section
+ - Include complete parameter definitions, request body schemas, and response schemas
+ - Use appropriate tags to categorize the endpoint
+ - Mark deprecated endpoints with `deprecated: true` flag
+ - Ensure response schemas reference existing components or define new ones
+
+4. **Enable token authentication** (if applicable):
+ - Add the route name to `api/config/sanctum-routes.php` if the endpoint should be accessible via Personal Access Tokens
+ - Use the exact route name as defined in the Laravel routes file (e.g., `open.workspaces.forms.index`)
+
+Example workflow: When adding a new workspace forms endpoint, you would create `docs/api-reference/forms/list-workspace-forms.mdx`, add it to the Forms group in `docs.json`, add the path definition to `openapi.yaml`, and add the route to `sanctum-routes.php` if needed.
+
### Accessibility requirements
+
- Include descriptive alt text for all images and diagrams
- Use specific, actionable link text instead of "click here"
- Ensure proper heading hierarchy starting with H2
@@ -338,6 +375,7 @@ description: "Concise description explaining page purpose and value"
## AI assistant instructions
### Component selection logic
+
- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions
- Use **Tabs** for platform-specific content or alternative approaches
- Use **CodeGroup** when showing the same concept in multiple languages
@@ -348,6 +386,7 @@ description: "Concise description explaining page purpose and value"
- Use **Expandable** for nested object properties or hierarchical information
### Quality assurance checklist
+
- Verify all code examples are syntactically correct and executable
- Test all links to ensure they are functional and lead to relevant content
- Validate Mintlify component syntax with all required properties
@@ -356,9 +395,10 @@ description: "Concise description explaining page purpose and value"
- Check for consistency in terminology, formatting, and component usage
### Error prevention strategies
+
- Always include realistic error handling in code examples
- Provide dedicated troubleshooting sections for complex procedures
- Explain prerequisites clearly before beginning instructions
- Include verification and testing steps with expected outcomes
- Add appropriate warnings for destructive or security-sensitive actions
-- Validate all technical information through testing before publication
\ No newline at end of file
+- Validate all technical information through testing before publication
diff --git a/api/config/sanctum-routes.php b/api/config/sanctum-routes.php
index e82840cc9..c9cfde952 100644
--- a/api/config/sanctum-routes.php
+++ b/api/config/sanctum-routes.php
@@ -27,6 +27,7 @@ return [
'open.workspaces.create',
'open.workspaces.update',
'open.workspaces.delete',
+ 'open.workspaces.forms.index',
// Workspace User Management
'open.workspaces.users.index',
diff --git a/docs/api-reference/forms/list-forms.mdx b/docs/api-reference/forms/list-forms.mdx
index fc7c0f410..03ed8d69f 100644
--- a/docs/api-reference/forms/list-forms.mdx
+++ b/docs/api-reference/forms/list-forms.mdx
@@ -2,7 +2,11 @@
openapi: get /open/forms
---
-# List Forms
+# List Forms (Deprecated)
+
+<Warning>
+**Deprecated**: This endpoint is deprecated. Use [List Workspace Forms](./list-workspace-forms) instead to retrieve forms for a specific workspace.
+</Warning>
Retrieve every form accessible to the authenticated user across **all** of their workspaces.
diff --git a/docs/api-reference/forms/list-workspace-forms.mdx b/docs/api-reference/forms/list-workspace-forms.mdx
new file mode 100644
index 000000000..edfc936ca
--- /dev/null
+++ b/docs/api-reference/forms/list-workspace-forms.mdx
@@ -0,0 +1,62 @@
+---
+openapi: get /open/workspaces/{workspaceId}/forms
+---
+
+Retrieve all forms within a specific workspace.
+
+## Authentication & Scope
+
+This request must be authenticated using a **Personal Access Token** that includes the `forms-read` ability.
+
+```http
+Authorization: Bearer <token>
+```
+
+## Request
+
+```http
+GET /open/workspaces/{workspaceId}/forms HTTP/1.1
+Host: api.opnform.com
+Authorization: Bearer <token>
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-------------|--------|----------------------------------|
+| workspaceId | number | ID of the workspace to retrieve forms from. |
+
+### Query Parameters
+
+| Parameter | Type | Description | Default |
+|-----------|--------|------------------------------------------------|---------|
+| page | number | Page number for pagination. | 1 |
+
+## Response
+
+`200 OK` – Returns a paginated JSON response containing Form objects.
+
+```json
+{
+ "data": [
+ {
+ "id": 42,
+ "slug": "customer-feedback",
+ "title": "Customer Feedback",
+ "visibility": "public",
+ "submissions_count": 15,
+ "properties": [
+ /* form fields & layout blocks */
+ ]
+ }
+ ],
+ "current_page": 1,
+ "per_page": 10,
+ "total": 1
+}
+```
+
+`403 Forbidden` – The token does not include the required `forms-read` ability, or you do not have access to the workspace.
+
+`404 Not Found` – The workspace does not exist.
+
diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml
index 95151a724..9f417b38a 100644
--- a/docs/api-reference/openapi.yaml
+++ b/docs/api-reference/openapi.yaml
@@ -362,12 +362,80 @@ paths:
example: Invite deleted successfully.
"403":
description: Forbidden
+ "/open/workspaces/{workspaceId}/forms":
+ get:
+ tags:
+ - Forms
+ summary: List Workspace Forms
+ description: "Retrieve all forms within a specific workspace. Requires `forms-read` ability."
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: workspaceId
+ in: path
+ required: true
+ schema:
+ type: number
+ description: ID of the workspace to retrieve forms from.
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: number
+ minimum: 1
+ default: 1
+ description: "Pagination page number"
+ responses:
+ "200":
+ description: Successful
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: "#/components/schemas/Form"
+ links:
+ type: object
+ properties:
+ first:
+ type: string
+ last:
+ type: string
+ prev:
+ type: string
+ nullable: true
+ next:
+ type: string
+ nullable: true
+ meta:
+ type: object
+ properties:
+ current_page:
+ type: number
+ from:
+ type: number
+ last_page:
+ type: number
+ per_page:
+ type: number
+ to:
+ type: number
+ total:
+ type: number
+ "403":
+ description: "Forbidden – token lacks forms-read ability or you do not have access to the workspace"
+ "404":
+ description: "Workspace not found"
"/open/forms":
get:
tags:
- Forms
summary: List Forms
- description: Retrieve all forms accessible to the token holder.
+ description: "Retrieve all forms accessible to the token holder across all workspaces. **Deprecated**: Use `/open/workspaces/{workspaceId}/forms` instead."
+ deprecated: true
security:
- bearerAuth: []
responses:
diff --git a/docs/docs.json b/docs/docs.json
index 679ce9b8f..e4b17a898 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -62,22 +62,10 @@
"api-reference/workspaces/delete-workspace"
]
},
- {
- "group": "Workspace Users",
- "pages": [
- "api-reference/workspace-users/list-workspace-users",
- "api-reference/workspace-users/list-workspace-invites",
- "api-reference/workspace-users/add-workspace-user",
- "api-reference/workspace-users/remove-workspace-user",
- "api-reference/workspace-users/update-workspace-user-role",
- "api-reference/workspace-users/leave-workspace",
- "api-reference/workspace-users/resend-workspace-invite",
- "api-reference/workspace-users/cancel-workspace-invite"
- ]
- },
{
"group": "Forms",
"pages": [
+ "api-reference/forms/list-workspace-forms",
"api-reference/forms/list-forms",
"api-reference/forms/create-form",
"api-reference/forms/get-form",
@@ -106,6 +94,19 @@
"api-reference/integrations/list-webhook-events"
]
},
+ {
+ "group": "Workspace Users",
+ "pages": [
+ "api-reference/workspace-users/list-workspace-users",
+ "api-reference/workspace-users/list-workspace-invites",
+ "api-reference/workspace-users/add-workspace-user",
+ "api-reference/workspace-users/remove-workspace-user",
+ "api-reference/workspace-users/update-workspace-user-role",
+ "api-reference/workspace-users/leave-workspace",
+ "api-reference/workspace-users/resend-workspace-invite",
+ "api-reference/workspace-users/cancel-workspace-invite"
+ ]
+ },
{
"group": "Zapier",
"pages": [