JSON-API

Authentifizierung

Erzeugen Sie einen persönlichen Schlüssel unter Mein Bereich → API-Schlüssel und senden Sie ihn im Authorization-Header jedes Aufrufs:

curl -H "Authorization: Bearer cpk_…" https://www.creationdeperso.com/api/v1/me

Der Schlüssel trägt die Rechte Ihres Kontos: Ein Spieler liest den Katalog und verwaltet seine Charaktere, ein Spielleiter schmiedet zusätzlich Monster und Gegenstände und schreibt Kampagnen und Quests.

Rechte eines Schlüssels

Jeder Schlüssel trägt eine bei der Erstellung gewählte (und später änderbare) Liste von Rechten: Einträge <code>family.action</code> oder eine ganze Familie <code>family.*</code>. Ein Recht übersteigt nie die Rollen des Kontos: Ein Schlüssel mit <code>monsters.create</code> auf einem Konto ohne SL-Rolle wird weiterhin abgelehnt. <code>GET /me</code> gibt die Rechte des Schlüssels zurück.

Ein Aufruf außerhalb der Rechte des Schlüssels antwortet mit <code>403 insufficient_scope</code> und dem fehlenden Recht in <code>requiredScope</code>.

Konventionen

• Katalogeinträge werden über ihren Slug (<code>key</code>) angesprochen, nie über eine numerische ID. Nur Charaktere, Kampagnen und Quests sowie die von Ihnen erstellten Ressourcen tragen eine <code>id</code>.
• Eine Liste ist in <code>{ items, total }</code> eingebettet (paginiert: <code>{ items, page, perPage, total }</code>, <code>perPage</code> ≤ 100).
• Der Header <code>Accept-Language</code> (Standard fr, en, de, es) bestimmt die Sprache der Katalognamen und Fehlermeldungen.
• Jedes Konto hat 1.000 Aufrufe pro Stunde (Header <code>X-RateLimit-*</code>).

Jeder Fehler antwortet mit einer einheitlichen Hülle:

{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "violations": [ { "path": "hitPoints", "message": "…" } ]
  }
}

Maximale Längen und Grenzen jedes Feldes (maxLength, minimum, maximum) stehen im OpenAPI-Schema: es sind die Regeln der Website, eine Überschreitung antwortet mit 422. Ein per GET gelesener Körper kann unverändert per PUT zurückgesendet werden, schreibgeschützte Felder eingeschlossen.

Katalog lesen

Lesen Sie zuerst den Katalog, um die zu sendenden Slugs zu kennen. Homebrew-Tabellen (Waffen, Rüstungen, Ausrüstung, Angriffe, Monster) sind auf das beschränkt, was Ihr Konto sehen darf: integrierte Inhalte, freigegebene öffentliche Inhalte und Ihre eigenen Kreationen (Feld <code>origin</code>).

Schmiede: Gegenstände und Monster (SL)

Dieselben Regeln wie die Schmiede der Website: Jede Erstellung kostet Guthaben (bei zu geringem Guthaben wird nichts geschrieben), Inhalte entstehen privat und durchlaufen die Moderation, bevor sie öffentlich werden, der Herausforderungsgrad eines Monsters darf nicht unter der Schätzung seiner Werte liegen. Änderungen und Löschungen sind kostenlos.

curl -X POST -H "Authorization: Bearer cpk_…" -H "Content-Type: application/json" \
     -d '{"name":"Gobelin des cendres","challengeRating":"1/4","armorClass":15,"hitPoints":7,
          "abilities":{"str":8,"dex":14,"con":10,"int":10,"wis":8,"cha":8},
          "skills":{"stealth":2},"attacks":[{"weapon":"scimitar"}]}' \
     https://www.creationdeperso.com/api/v1/monsters

Kampagnen und Quests (SL)

Der Spielleiter ist immer das aufrufende Konto. Charaktere werden per <code>id</code> angesprochen: Ein Gruppenmitglied muss öffentlich und beansprucht sein, ein gebundener NSC einer Ihrer Bögen, ein Gast öffentlich, beansprucht und außerhalb der Gruppe. Eine bearbeitete öffentliche Kampagne oder Quest wartet wieder auf Freigabe.

Charaktere

Die Erstellung folgt genau den Regeln des Formulars der Website: die sechs Werte müssen eine Permutation des vom Server erzeugten Wurfs sein (über den Wurf-Endpunkt bezogen und als Ticket <code>abilityRollToken</code> zurückgegeben, fünf Minuten gültig und nur einmal verwendbar), eine Abstammung ist Pflicht, wenn die Spezies welche hat, die Hintergrund-Verteilung muss zulässig sein, und Fertigkeiten, Talente, Zauber und Ausrüstung bleiben in den Budgets der Stufe 1. Ein Regelverstoß antwortet mit 422 und dem Pfad des betroffenen Feldes.

Das vollständige maschinenlesbare Dokument wird als OpenAPI bereitgestellt.