Title here
Summary here
HTTP & middleware
The Moonlight API uses one versioned URL, but Pionia still speaks real HTTP — status codes, headers, and middleware chains matter for production apps like DeskFlow.
Guide map
| Topic | Page |
|---|---|
| Envelopes & status codes | Requests & responses |
| Working with JSON payloads | Collections |
| Global request pipeline | Middleware |
| Errors & validation | Exceptions |
| Static routes & SPA fallback | HTTP routing |
DeskFlow example
When Alex creates a task without a title, DeskFlow returns HTTP 422 with returnCode in the JSON body — see Validation and Exceptions.
Add RequestIdMiddleware so support tickets reference a single request ID — covered in Middleware.
Suggested order
- Requests & responses — envelopes first
- Collections — read JSON in actions
- Exceptions — 422 when title is missing
- Middleware — request IDs for support
- HTTP routing — static files and SPA fallback
Building your API
Services that produce these responses.
Security
Auth runs after middleware.
Common mistakes
- Debugging in actions before reading envelopes — start with Requests & responses so status codes make sense.
- Adding middleware for auth — authentication backends run after middleware; use
mustAuthenticate()on services. - Expecting RESTful paths per action — Moonlight uses
POST /api/v1/with a JSON body, not/api/v1/task/list.