API · v1 · stabil
CODEMETA OSDeveloper Center
Konsole öffnen
Konzept

Plattform-Garantien

Lesedauer · 8 Min.Aktualisiert · 2026-05-01

Diese Seite fasst die Verträge zusammen, auf die Sie sich beim Bauen gegen die API verlassen können. Sie sind über alle Module identisch.

1. Authentifizierung — opake Sessions

Codemeta OS verwendet keine JWTs. Sign-in erzeugt eine Session, die als HTTP-Only-Cookie ausgegeben wird. Die Session ist serverseitig gespeichert und kann jederzeit invalidiert werden (z. B. nach Passwort-Reset oder Sign-out).

  • Sign-in: POST /api/auth/sign-in/email
  • Sign-out: POST /api/auth/sign-out
  • 2FA ist plattformweit verpflichtend.

2. Mandantenkontext — X-Tenant-Id

Jeder Aufruf gegen /api/v1/... braucht den Header. Mehr unter Multi-Tenancy.

3. Idempotenz für POST — X-Idempotency-Key

POST-Requests, die das Anlegen einer Entity auslösen, akzeptieren einen X-Idempotency-Key-Header. Wiederholte Requests mit demselben Key + Body liefern dieselbe Antwort, ohne eine zweite Entity zu erzeugen. Empfehlung: UUIDv4 pro logischem Vorgang.

4. Fehlerformat — RFC 7807

Alle Fehlerantworten folgen RFC 7807. Das Schema:

{
  "type": "https://codemeta-os.de/probs/<slug>",
  "title": "Kurzbeschreibung",
  "status": 422,
  "detail": "Optionaler längerer Text.",
  "errors": [
    { "path": "/email", "message": "Pflichtfeld" }
  ]
}

type ist eine stabile URI – die richtige Stelle für Code-Switches in Ihrem Client. title ist menschenlesbar und kann sich ändern. errors[] ist optional und nur bei Validierungsfehlern (422) gesetzt.

5. Pagination

Listen-Endpoints liefern immer eine Seite, nie den kompletten Bestand. Die Seite steht in data, die Blätter-Information in meta. Geblättert wird wahlweise über offset oder cursor:

curl "https://os.codemeta.de/api/v1/tickets?limit=50&offset=100" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

Die Antwort:

{
  "data": [ … ],
  "meta": {
    "nextCursor": "0192f2c0-…",
    "hasMore": true,
    "limit": 50
  }
}

limit ist auf 200 begrenzt und wird darüber hinaus still gekappt. Eine exakte Trefferzahl (meta.total) liefern wir nur auf Anfrage mit ?withTotal=true. Details, Fallstricke und ein vollständiger Durchlauf stehen unter Pagination.

6. IDs — UUIDv7

Alle Entity-IDs sind UUIDv7. Sie sind chronologisch sortierbar und global eindeutig. Wir geben niemals ObjectIds heraus.

7. Audit — RFC 6902

Jede Mutation erzeugt einen JSON-Patch-Audit-Eintrag in derselben Transaktion wie die Datenänderung. Mehr unter Audit-Historie.

8. Soft-Deletion

DELETE löscht nicht physisch. Mehr unter Soft-Deletion.

9. Sprache & Lokalisierung

Die API antwortet in Deutsch (Default) oder Englisch (Fallback) – steuerbar über den Accept-Language-Header. Validierungsfehler werden serverseitig lokalisiert; Maschinen-Codes (type) bleiben sprachunabhängig.

Was die Plattform nicht verspricht

  • Hard-Delete. Findet außer im DSGVO-Erase-Workflow nicht statt.
  • Beliebige Reihenfolge bei Patches. Wer version ignoriert, riskiert Lost-Updates – siehe Optimistic Locking.
  • Stabile title/detail-Texte in Fehlern. Diese können sich ändern.
  • Synchron persistierte Webhook-Auslieferung. Webhooks werden asynchron zugestellt – mehr unter Webhooks.

Verwandte Konzepte

Suche