Konventionen

Inhalt

Konventionen#

Diese gelten für die ganze Schnittstelle. Wer das einmal liest, muss es nicht bei jeder Ressource neu herausfinden.

Versionierung#

Die Version steht im Pfad: /api/public/v1/.

Additive Änderungen — neue Felder, neue Endpunkte, neue optionale Parameter, neue Enum-Werte — kommen innerhalb von v1. Dein Client muss sie vertragen, und dafür braucht es zwei Gewohnheiten: ignoriere Antwortfelder, die du nicht kennst, und brich nicht bei einem unbekannten Enum-Wert ab.

Entfernungen, Umbenennungen, Typwechsel und alles, was die Validierung verschärft, erhöhen die Version, mit einem Überlappungsfenster, in dem beide laufen.

Antworten auf Listenabfragen#

Listen sind cursor-paginiert und kommen immer in derselben Hülle zurück:

{
  "object": "list",
  "data": [ { "object": "shift", "id": "0194d1c0-…", "…": "…" } ],
  "has_more": true,
  "next": "https://app.shiftavo.com/api/public/v1/shifts/?cursor=…"
}

next ist eine undurchsichtige URL. Folge ihr unverändert; bau oder zerleg keine Cursor.
Hör auf, wenn has_more false ist.
page_size steuert die Seitenlänge.

Der Unterscheider `object`#

Jede Ressource führt ein Feld "object", das ihren Typ nennt — "shift", "location", "employee". Verzweige darüber statt über die Form der Nutzlast, besonders in Webhook-Handlern und gemischten Sammlungen.

Fehler#

Eine Hülle, überall:

{
  "error": {
    "type": "conflict_error",
    "code": "not_cancellable",
    "message": "…",
    "details": [],
    "param": "start_date"
  }
}

details ist immer vorhanden — eine Liste der Fehler auf Feldebene, leer, wenn der Fehler keine Aufschlüsselung nach Feldern hat.
param erscheint nur, wenn genau ein Feld schuld ist.

Es gibt sieben Typen. Jeder bildet auf einen Status ab, ausser invalid_request_error, dem Sammelbecken für die nicht tabellierten 4xx, wo der code die Unterscheidung trägt:

`type`	Status	Hinweise
`invalid_request_error`	400 · 405 · 406 · 415	`code` = `invalid_request` / `method_not_allowed` / `not_acceptable` / `unsupported_media_type`
`idempotency_error`	400	`Idempotency-Key` mit einem anderen Body wiederverwendet (`idempotency_key_reused`)
`authentication_error`	401	fehlendes / ungültiges / abgelaufenes Token
`permission_error`	403	`insufficient_scope` und Verwandte
`not_found`	404	wird auch statt 403 für Datensätze ausserhalb deines Unternehmens zurückgegeben — kein Rückschluss auf die Existenz
`conflict_error`	409	Zustandskonflikte: `duplicate`, `in_use`, `not_deletable`, eine laufende idempotente Wiederholung
`rate_limit_error`	429	bringt `Retry-After` mit

Verzweige über type für die Behandlungsklasse und über code für den konkreten Fall. Beide sind stabil; message ist es nicht — behandle es nur als für Menschen lesbar.

Idempotenz#

Sende bei Erstellungen einen Idempotency-Key-Header. Eine wiederholte Anfrage spielt dann das erste Ergebnis erneut aus, statt einen zweiten Datensatz anzulegen.

Denselben Schlüssel mit einem anderen Body zu verwenden, ergibt einen 400 idempotency_key_reused — der Schlüssel bezeichnet eine Anfrage, nicht einen Endpunkt.

Anfragen nachverfolgen#

Jede Antwort, bei Erfolg wie bei Fehler, trägt einen X-Request-Id-Header. Protokollier ihn. Sendest du selbst ein X-Request-Id, wird es zurückgespiegelt, sodass eine Trace-ID von Ende zu Ende mitlaufen kann. Nenn sie in jeder Supportanfrage.

Übergänge im Lebenszyklus#

Ein Übergang wird als POST auf einen Aktions-Unterpfad ausgelöst: POST …/<id>/publish/, …/cancel/, …/revoke/.

Ein Übergang, der nicht möglich ist — einen Entwurf absagen, etwas bereits Veröffentlichtes veröffentlichen —, ist ein 409 mit einem eigenen Code (not_cancellable, not_publishable, not_unpublishable). Nie ein 200, das stillschweigend nichts getan hat.

Löschen#

DELETE gibt einen Stummel zurück, keinen 204:

{ "id": "0194d1c0-…", "object": "shift", "deleted": true }

Ein DELETE hat nie einen Body. Alles, was ein Löschvorgang braucht, steht im Pfad oder in der Query, sodass ein generierter Client alle Fälle ausdrücken kann. (HTTP lässt die Bedeutung eines DELETE-Bodys offen, und OpenAPI 3.0 sagt Konsumenten, einen solchen zu ignorieren — ein Body-Feld hier würde also stillschweigend aus deinem Client verschwinden und als 400 zurückkommen, den das Schema nicht erklären könnte.)

Löschen ist nicht das sanfte Verb#

Wo eine Ressource beides anbietet, sind sie keine Synonyme, und die falsche Wahl lässt sich nicht rückgängig machen:

Ressource	`DELETE …/<id>/`	Das sanfte Verb
`shifts`	entfernt die Schicht; die Zugeteilten einer veröffentlichten Schicht werden benachrichtigt, und ein laufendes Angebot in der Schichtbörse wird vorher zurückgezogen	`POST …/cancel/` — die Schicht bleibt, als abgesagt markiert
`employees`	endgültige Entfernung: Zugang entzogen, die Person verschwindet aus jeder Sammlung, und ein späterer `GET` ist ein `404`. Der Datensatz bleibt intern erhalten, damit Stundenrapporte und Abwesenheiten ihre Verweise behalten	`POST …/deactivate/` (umkehrbar) · `POST …/offboard/` (datierter Austritt + Abrechnung)
`leave_requests`	nur solange ausstehend oder abgelehnt — ein bestätigter oder zurückgezogener Antrag trägt eine Journalbuchung, deshalb ein `409 not_deletable`	`POST …/revoke/` — macht die Wirkung rückgängig, behält den Datensatz

Wiederkehrende Datensätze#

Das Löschen eines einzelnen Vorkommens eines wiederkehrenden shifts- oder availability-Datensatzes braucht einen ausdrücklichen Geltungsbereich:

DELETE …/<id>/?scope=this|following|all        # shifts
DELETE …/<id>/?scope=single|following|all      # availability

Lässt du ihn bei einer Serie weg, bekommst du einen 409 delete_scope_required statt einer Vermutung darüber, was du gemeint hast.

Ratenbegrenzungen#

Ein 429 bringt einen Retry-After-Header mit. Halt dich daran und warte bei Wiederholungen exponentiell länger.