Skip to content

🎨 Palette: Improve API Error Messages and Documentation Clarity #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amrabed merged 1 commit into from
Jul 8, 2026
Merged

🎨 Palette: Improve API Error Messages and Documentation Clarity #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/template/agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,11 @@ def get_item(item_id: str) -> dict:

### Item model

Field | Type | Description
--- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars)
`name` | string | Human-readable item name (1-100 chars)
`description` | string | Human-readable item description (max 500 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars) | No
`name` | string | Human-readable item name (1-100 chars) | Yes
`description` | string | Human-readable item description (max 500 chars) | No


### Environment variables
Expand Down
10 changes: 5 additions & 5 deletions docs/template/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ mise run deploy api

Endpoint | Description | Response codes
--- | --- | ---
`GET /items/{id}` | Retrieve an item by ID | 200 (OK), 404 (Not Found), 500 (Internal Server Error)
`GET /items/{id}` | Retrieve an item by ID | 200 (OK), 400 (Bad Request), 404 (Not Found), 500 (Internal Server Error)
`POST /items` | Create a new item | 201 (Created), 422 (Unprocessable Entity), 500 (Internal Server Error)

### Item model

Field | Type | Description
--- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars)
`name` | string | Human-readable item name (1-100 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars) | No
`name` | string | Human-readable item name (1-100 chars) | Yes

### Environment variables

Expand Down
8 changes: 4 additions & 4 deletions docs/template/eventbridge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ Model | Description
#### ApiResponse
Written to the DynamoDB table after calling the external API.

Field | Type | Description
--- | --- | ---
`id` | string | Unique identifier of the API response record (1-50 chars)
`message` | string | Message returned by the external API (1-1000 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | string | Unique identifier of the API response record (1-50 chars) | No
`message` | string | Message returned by the external API (1-1000 chars) | Yes

### Environment variables

Expand Down
8 changes: 4 additions & 4 deletions docs/template/graphql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,10 @@ def create_item(name: str) -> dict:

### Item model

Field | Type | Description
--- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars)
`name` | string | Human-readable item name (1-100 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | UUID string | Unique item identifier (auto-generated, 1-50 chars) | No
`name` | string | Human-readable item name (1-100 chars) | Yes

### Environment variables

Expand Down
12 changes: 6 additions & 6 deletions docs/template/s3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,12 @@ mise run deploy s3

### ProcessedMessage model

Field | Type | Description
--- | --- | ---
`bucket` | string | S3 bucket name (3-63 chars)
`key` | string | S3 object key (1-1024 chars)
`event_time` | string | ISO-8601 event timestamp
`source` | string | Origin event source (`s3`)
Field | Type | Description | Required
--- | --- | --- | ---
`bucket` | string | S3 bucket name (3-63 chars) | Yes
`key` | string | S3 object key (1-1024 chars) | Yes
`event_time` | string | ISO-8601 event timestamp | Yes
`source` | string | Origin event source (`s3`) | No (default: `s3`)

### Environment variables

Expand Down
18 changes: 9 additions & 9 deletions docs/template/sqs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,19 +31,19 @@ mise run deploy sqs
#### SqsMessage
Parsed from the SQS message body.

Field | Type | Description
--- | --- | ---
`id` | string | Unique identifier for the message (1-50 chars)
`content` | string | The main content of the message (1-1000 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | string | Unique identifier for the message (1-50 chars) | No
`content` | string | The main content of the message (1-1000 chars) | Yes

#### ProcessedItem
Written to the DynamoDB table.

Field | Type | Description
--- | --- | ---
`id` | string | Unique identifier for the item (partition key, 1-50 chars)
`content` | string | The processed content (1-1000 chars)
`status` | string | Processing status (1-50 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | string | Unique identifier for the item (partition key, 1-50 chars) | No
`content` | string | The processed content (1-1000 chars) | Yes
`status` | string | Processing status (1-50 chars) | Yes

### Environment variables

Expand Down
16 changes: 8 additions & 8 deletions docs/template/stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,18 +33,18 @@ mise run deploy stream
#### SourceItem
Read from the source table stream.

Field | Type | Description
--- | --- | ---
`id` | string | Unique item identifier (1-50 chars)
`name` | string | Human-readable item name (optional, 1-100 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | string | Unique item identifier (1-50 chars) | Yes
`name` | string | Human-readable item name (optional, 1-100 chars) | No

#### DestinationItem
Written to the destination table.

Field | Type | Description
--- | --- | ---
`id` | string | Unique item identifier (1-50 chars)
`name` | string | Human-readable item name (optional, 1-100 chars)
Field | Type | Description | Required
--- | --- | --- | ---
`id` | string | Unique item identifier (1-50 chars) | Yes
`name` | string | Human-readable item name (optional, 1-100 chars) | No

### Environment variables

Expand Down
7 changes: 5 additions & 2 deletions templates/api/handler.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ def get_item(id: str) -> Response:
try:
Entity(id=id)
except ValidationError:
return JsonResponse({"message": "Invalid item ID length"}, status_code=400)
return JsonResponse({"message": "Item ID must be between 1 and 50 characters"}, status_code=400)

try:
if (item := repository.get_item(id)) is None:
Expand All @@ -57,7 +57,10 @@ def create_item() -> Response:
try:
item = Item.model_validate_json(app.current_event.body)
except ValidationError as exc:
return JsonResponse({"errors": exc.errors(include_input=False, include_url=False)}, status_code=422)
return JsonResponse(
{"message": "Validation failed", "errors": exc.errors(include_input=False, include_url=False)},
status_code=422,
)

try:
repository.put_item(item.dump())
Expand Down
4 changes: 3 additions & 1 deletion tests/api/test_handler.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ def test_get_item_id_too_long(mock_repo, lambda_context):

assert response["statusCode"] == 400
body = loads(response["body"])
assert body["message"] == "Invalid item ID length"
assert body["message"] == "Item ID must be between 1 and 50 characters"


def test_post_item_invalid_body(mock_repo, lambda_context):
Expand All @@ -121,6 +121,7 @@ def test_post_item_invalid_body(mock_repo, lambda_context):

assert response["statusCode"] == 422
body = loads(response["body"])
assert body["message"] == "Validation failed"
assert "errors" in body


Expand All @@ -134,6 +135,7 @@ def test_post_item_name_too_long(mock_repo, lambda_context):

assert response["statusCode"] == 422
body = loads(response["body"])
assert body["message"] == "Validation failed"
assert "errors" in body
assert any(err["type"] == "string_too_long" for err in body["errors"])
# Verify sanitization (no input, no url)
Expand Down