# What is an API Contract Task?

**Location:** planning docs · **Not application feature code**

## Simple meaning

An **API Contract** task means: **before** (or in parallel with) writing real backend code, the owner writes down the exact API shape in a short doc:

- URL + HTTP method  
- Request JSON  
- Response JSON  
- Validation errors (422)  
- Permissions  
- Status codes (401/403/404/409)  
- Filters / pagination  
- One example payload  

Frontend (Bablu) can then build screens with **mock data** matching that contract. Backend implements the same contract. They do not wait for each other to finish coding.

```text
Bad (serial):
  Backend fully done  →  then Frontend starts

Good (parallel):
  API Contract locked
       ├─→ Backend implementation
       └─→ Frontend implementation (mock → live)
```

## What it is NOT

- Not a second product feature  
- Not OpenAPI codegen requirement (markdown/OpenAPI either is fine)  
- Not full commission calculation  
- Not “fake APIs in production”

## Where are the sample responses?

Concrete request/response JSON for every `PMS-API-*` lives here:

**[11-api.md](./11-api.md)**

Includes:
- ERPFlow envelope (`success` / `message` / `data` / `errors`)
- Project Types, Services, Divisions/Roles
- Projects, Project Services, Contracts
- Commission Share (with $100 → $30 → $12/$18 example)
- Service Teams / Permanent members
- Contract Assignment + Act-As (Rahim sample)
- Payment cleared event payload
- Report row sample

## Who owns which contracts

| Contract ID | Owner |
| --- | --- |
| PMS-API-0 | Ashraful |
| PMS-API-1.1, 1.2, 1.3, 1.4 | Sharif |
| PMS-API-2.1, 2.2, 2.3, 2.5 | Ashraful |
| PMS-API-3.1, 3.3 | Munna |

Paste-ready cards for these live in `docs/projects/PMS_PHASE1_TASK_CARDS.md`.