This specification contains two kinds of notes.
Reasons from the system's side: why something takes this form, given the data and the implementation.
From the user's side
Reasons from the user's side: where people get stuck, and what the screen should do about it.
API contract
These five endpoints are a proposed service contract. The standalone dashboard uses an in-memory gateway and does not implement these HTTP endpoints. Deletion and publishing describe wider service functions.
First, the front end sets out what data each screen needs and when. The back-end engineer checks this against the database structure and proposes what can be returned. Then the front end decides how to handle the values that come back. Each endpoint records this exchange.
1What the front end asked for
2What came back from the back end
3What was decided as a result
1. Get the day's schedule
GET /api/shifts/daily?date=2026-10-15
1The screen needs, for each current staff member, whether they are scheduled in each of the eight slots, and the shop’s work-period rule. Names are for display; matching should use IDs.
2Slots are stored sparsely, so as they stand they would come back with gaps. Returning every slot filled is possible.
3Return eight boolean time values per current staff member. A person may be off duty or work one continuous period of at least three hours.
Request and response shapes
{
"date": "2026-10-15",
"status": "draft",
"revision": 0,
"updatedAt": "2026-10-14T17:42:00Z",
"businessHours": { "start": "09:00", "end": "17:00", "slotCount": 8 },
"workRules": { "minConsecutiveHours": 3, "allowSplitShifts": false },
"staff": [
{
"staffId": "st_001",
"name": "Anna",
"active": true,
"slots": [true, true, true, true, false, false, false, false]
}
],
"permissions": { "canEdit": true, "canPublish": false }
}Return the saved schedule and its revision together. Mutations send expectedRevision; the server checks it atomically before replacing the day. updatedAt is display metadata.
businessHours and workRules are returned per screen. The back end supplies the opening hours and the work-period rule, so the front end does not hard-code them.
permissions is included in the response. The front end holds no permission logic, only the server's decision, so changing the rules needs no front-end change. This shape was the back end's suggestion. Permissions and the published status belong to the wider service design.
name is for display only. The CSV uses staffId alone; names are not used for matching, since people can share a name or change it.
2. Download the saved schedule as CSV
GET /api/shifts/daily/csv?date=2026-10-15
→ text/csv
date,staff_id,09:00-10:00,10:00-11:00,11:00-12:00,12:00-13:00,13:00-14:00,14:00-15:00,15:00-16:00,16:00-17:00
2026-10-15,st_001,TRUE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,FALSE
...
The CSV comes with the date filled in. Typing it by hand makes B6 more likely.
Every current staff member is included with all eight time fields, including those off duty. Building rows by hand makes A4 frequent.
Only current staff are included, so A1 mostly happens when an old file is reused.
Return the saved schedule, not an empty template. After recovery from conflict or an unknown result, download a fresh copy and transfer any edits made to an older file.
3. Upload (validate and replace)
POST /api/shifts/daily/upload
Content-Type: multipart/form-data
date: 2026-10-15
expectedRevision: 0
file: (CSV)
1The screen should show which row and which value is the problem. Some errors have row numbers and some belong to a staff member or a period, so please do not force them into one shape.
2Validation runs on the server, so the codes are defined here. Returning every error would make the response large, so there should be a cap, returning only the count beyond it.
3Codes are defined by the back end, and the front end prepares the matching messages. Error shapes differ by unit of reporting: some carry a row number, some a staff ID and a period. In this proposed API, errors beyond a cap come as a count in truncated.omitted, and the screen shows "n more problems". The standalone dashboard returns every issue it finds.
Response shapes (200 / 422 / 409)
200 — applied
{
"result": "applied",
"revision": 1,
"updatedAt": "2026-10-14T17:43:00Z",
"warnings": [
{ "start": 0, "end": 1, "count": 1 },
{ "start": 7, "end": 8, "count": 0 }
]
}422 — blocked
{
"result": "rejected",
"blocking": [
{ "code": "DATE_MISMATCH", "row": 2, "expected": "2026-10-15", "found": "2026-10-16" }
],
"errors": [],
"truncated": { "omitted": 0 }
}422 — corrections needed
{
"result": "rejected",
"blocking": [],
"errors": [
{ "code": "SHIFT_TOO_SHORT", "staffId": "st_001", "start": 0, "end": 2 },
{ "code": "SPLIT_SHIFT", "staffId": "st_003", "periods": [{ "start": 0, "end": 3 }, { "start": 4, "end": 7 }] },
{ "code": "SCHEDULE_VALUE_INVALID", "row": 4, "slot": 2, "value": "yes" },
{ "code": "STAFF_ROW_MISSING", "staffId": "st_002" }
],
"truncated": { "omitted": 0 }
}409 — edit conflict
{
"result": "conflict",
"code": "STALE_DATA",
"revision": 1,
"updatedAt": "2026-10-14T17:43:00Z"
}blocking and errors are separate arrays. A blocking error stops at the first, so the array always has one item, but keeping the shape means the contract survives if several are returned later. Warning periods use start and end slot indexes: start is included, end is not, and 0 is 09:00.
Error shapes vary by item: some have row, some have staffId and a period. One shared shape would add "no row number" branches on screen. Different units of reporting get different shapes.
Replacement runs in a single transaction: it is either fully applied or not applied. A lost response leaves the client unable to tell which occurred. For S1, reload the day and its revision before another upload. If an older revision is submitted, S4 rejects the outdated write.
4. Delete
DELETE /api/shifts/daily?date=2026-10-15
expectedRevision: 0
Deletion also requires expectedRevision. It is as destructive as replacement, so conflict detection works the same way. Deletion belongs to the wider service design.
Deletion is per day only. Deleting several days at once is a separate endpoint, outside this specification. Putting actions with different reach on one endpoint would complicate permissions.
5. Change publishing status
PATCH /api/shifts/daily/status
{ "date": "2026-10-15", "status": "published", "expectedRevision": 1 }Changing status is separate from upload. Publishing on upload would leave no way to check before publishing. Publishing belongs to the wider service design.
Notifying staff is triggered on the server. If the front end called a notification API, publishing could succeed while notification fails.