Building your API

All business logic in a Pionia app lives in services — PHP classes with one method per action. DeskFlow clients POST JSON to http://127.0.0.1:8000/api/v1/:

{ "service": "task", "action": "list" }

Who this is for

You finished DeskFlow tutorial Step 1 and want to design DeskFlow’s Moonlight API — services, actions, validation, and optional generic CRUD for task, member, and project.

What you will learn

How { "service", "action" } maps to PHP classes and *Action methods
When to use hand-written services vs Generic services
How to document actions for frontend teams at /docs

Before you start

Introduction — DeskFlow scaffold and ping curl
Moonlight overview — envelope and switch model

How it works

flowchart LR POST["POST /api/v1/"] --> Switch[MainSwitch] Switch --> Task[task → TaskService] Switch --> Member[member → MemberService] Switch --> Project[project → ProjectService] Task --> Action[listAction / createAction]

Start here

Topic	Page
Architecture overview	Moonlight overview
Your first service	Services
Action methods	Actions
Input rules	Validation
CRUD without boilerplate	Generic services

DeskFlow services

In the DeskFlow tutorial you build:

Service	Purpose
`task`	List, create, and assign tasks
`member`	Login and team profiles
`project`	Group tasks by client project

Reference

API versioning — when Northwind adds /api/v2/
Moonlight security model — auth at the switch layer
Documenting your API — @moonlight-* and OpenAPI

Every response uses the same envelope: returnCode, returnMessage, returnData. See Requests & responses.

Common mistakes

Legacy uppercase JSON keys — Moonlight expects lowercase service and action.
Skipping switch registration — scaffolding TaskService is not enough; add 'task' => TaskService::class in MainSwitch::registerServices().
Using generic services for complex rules — keep TaskService manual when assignee logic grows; use ProjectService as generic CRUD first.
Wrong dev port — DeskFlow examples use 8000 (PORT in environment/.env), not 3000 or 8003.