bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): refresh Form Builder public API surface notes

Browse Source 
Updates API.md and S3a discovery doc to reflect submitter-details
handling and the draft/submit split.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-23 17:21:15 +02:00
parent fe70a4d242
commit d67502eaec
2 changed files with 31 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
dev-docs/API.md
View File

@@ -784,16 +784,34 @@ S2c contract for the unauthenticated portal. Six endpoints at
`PublicFormTokenResolver` (7-day grace window on
`public_token_previous`; BACKLOG FORM-04 makes this configurable).
All errors use the standardised envelope:
### Error envelope
All public form endpoints return errors with this envelope:
```json
{ "message": "Human text", "code": "MACHINE_CODE", "errors"?: {"values.slug": ["..."]} }
{
"message": "Human-readable message",
"code": "MACHINE_READABLE_CODE",
"errors": { "field_name": ["validation message"] }
}
```
Codes: `SCHEMA_NOT_FOUND` (404), `TOKEN_EXPIRED` (410),
`TOKEN_REVOKED` (410), `SCHEMA_UNPUBLISHED` (410),
`SUBMISSION_ALREADY_SUBMITTED` (409), `RATE_LIMITED` (429, carries
`Retry-After`), `VALIDATION_FAILED` (422).
`errors` is only present on 422 validation failures (Laravel
FormRequest shape).
Codes:
| Code | HTTP | Meaning |
| ----------------------------- | ---- | ---------------------------------------------- |
| `TOKEN_EXPIRED` | 410 | public token past grace window |
| `TOKEN_REVOKED` | 410 | token rotated without grace |
| `SCHEMA_UNPUBLISHED` | 410 | schema exists but not published |
| `SCHEMA_NOT_FOUND` | 404 | public token does not resolve |
| `SUBMISSION_ALREADY_SUBMITTED`| 409 | submit on finalised submission |
| `RATE_LIMITED` | 429 | includes `Retry-After` header |
Authoritative source: `api/app/Exceptions/FormBuilder/PublicFormApiException.php`
and its concrete subclasses.
### `GET /public/forms/{public_token}`

7
dev-docs/discovery/S3a-public-form-api.md
View File

@@ -1,5 +1,12 @@
# Discovery — Public Form Builder API surface (S3a prep)
> **Superseded 2026-04-18**
> Written against commit 79d834c (S2b + S0.5) for S3a discovery.
> S2c standardised the error envelope to `{ message, code, errors? }`
> — see /dev-docs/API.md § Public Form Endpoints for the current
> contract. Route inventory and response shapes below remain
> accurate; only the error envelope changed.
> **Purpose:** ground a follow-up S3a frontend prompt in the exact shapes
> the current backend exposes. Written by inspecting code + hitting the
> live endpoints against the S0.5-seeded dev token, not from ARCH or