Jede API-Operation hat jetzt einen festen Namen — und qr3.app sagt, wofür es taugt

Eine API wird heute von zwei sehr verschiedenen Lesern ausgewertet: von einem Codegenerator, der daraus ein SDK baut, und von einem Assistenten, der entscheiden soll, ob er sie überhaupt aufrufen will. Beiden fehlte bisher etwas Grundsätzliches.

Jede Operation hat einen Namen

Die OpenAPI-Beschreibung nannte zu jeder der 75 Operationen Zweck, Parameter und Antwortformen — aber nicht ihren Namen. Das Feld dafür heißt operationId, und es fehlte durchgehend.

Ohne dieses Feld muss sich ein Generator einen Namen zusammensetzen, meist aus HTTP-Methode und Pfad. Aus POST /v1/codes wird dann postV1Codes, und aus GET /v1/codes/{id}/scans etwas wie getV1CodesIdScans. Solche Namen sind lesbar, aber sie hängen am Pfad: Wer den Pfad umbaut, benennt ungewollt die Methode um, die in fremdem Code steht.

Jetzt steht der Name in der Spezifikation:

"/v1/codes": {
  "get":  { "operationId": "listCodes"  },
  "post": { "operationId": "createCode" }
}

Die Form ist an allen 75 Stellen dieselbe: list…, get…, create…, update…, replace…, delete… — und wo die Handlung keinem dieser Muster folgt, das Verb der Sache selbst, etwa validateDpp oder registerGs1Identifier. Das Verb richtet sich nach der Fachlichkeit, nicht nach der HTTP-Methode: archiveWorkspace ist ein DELETE, importDpps ein POST.

Denselben Namen benutzen auch Werkzeug-Kataloge beim Function Calling. Ein Assistent, der die Spezifikation einliest, sieht ab jetzt createCode statt postV1Codes — und der Name bleibt gleich, auch wenn sich der Pfad einmal ändert.

Eine Wann-Anleitung statt einer Bestandsliste

https://qr3.app/llms.txt ist die Datei, die ein Assistent liest, bevor er irgendetwas anderes von qr3.app liest. Sie zählte bisher auf, was es gibt — nie, wann es passt. Der neue Abschnitt ## When to use qr3.app nennt sechs Aufgaben statt sechs Funktionen: ein gedruckter Code, dessen Ziel sich später noch ändern muss; eine DPP-Pflicht aus der EU-Verordnung; die Auflösung einer GS1-Kennung; Massenerzeugung; Messung ohne Personenbezug; ein Agent, der handeln und nicht nur lesen soll.

Dazu gehört ein Satz, der die Grenze zieht — wofür qr3.app nicht das richtige Werkzeug ist. Ohne ihn wäre der Abschnitt Werbung und keine Anleitung.

Dieselbe Auskunft liegt jetzt im Handschlag des MCP-Servers. Wer ihn in Claude, ChatGPT oder einem eigenen Client einbindet, sah bisher elf Werkzeuge und keinen Satz dazu, wofür sie gedacht sind:

curl -s -X POST https://mcp.qr3.app/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"probe","version":"1"}}}'

Die Antwort enthält jetzt ein Feld instructions mit derselben Wann-Anleitung und dem Hinweis, welche Aufrufe einen API-Schlüssel brauchen und welche nicht.

Vier Angaben, die nicht stimmten

Beim Durchgehen von llms.txt haben wir jede Behauptung darin gegen Produktion gemessen. Vier hielten nicht stand und sind entfernt oder korrigiert:

• Ein Python-SDK gibt es noch nicht. llms.txt nannte ein Paket qr3app auf PyPI samt pip install-Zeile. Das Paket ist dort nicht veröffentlicht. Wer der Zeile gefolgt ist, bekam einen Fehler — die Angabe ist ersatzlos raus, bis das Paket wirklich erscheint. Die SDKs für JavaScript/TypeScript, Go und PHP sowie CLI und MCP-Server sind davon nicht betroffen.
• Markdown gilt nicht für jede Seite. Es hieß, jede serverseitig gerenderte Seite beantworte Accept: text/markdown. Tatsächlich tun das die Startseite und der Blog; die übrigen Seiten werden beim Bauen erzeugt und bleiben HTML. Jetzt steht die zutreffende Aussage samt Grenze dort.
• Die Kontaktadresse war an zwei Stellen — in llms.txt und in den strukturierten Daten der Startseite — eine andere als im Impressum. Überall gilt jetzt [email protected].
• Ein Link versprach eine Seite, die es nicht gibt: /de/security/ ist eine Weiterleitung auf den Abschnitt „Sicherheit” der Startseite. Der Link führt jetzt dorthin, wo er ankommt.

Zusätzlich verlinkt llms.txt jetzt die Seite docs.qr3.app/de/skills/. Sie war vorhanden, stand aber in keiner Sitemap und in keiner Übersicht — vorhanden und unauffindbar zugleich.

Was Sie tun müssen

Für laufende Integrationen: nichts. Pfade, Parameter und Antwortformen sind unverändert, operationId kommt zusätzlich hinzu.

Eine Ausnahme mit Ansage: Wenn Sie sich Ihr eigenes SDK aus unserer OpenAPI-Datei generieren, benennt Ihr Generator die Methoden beim nächsten Lauf um — von postV1Codes auf createCode. Das ist der Sinn der Änderung, aber es ist eine Umbenennung in Ihrem Code. Wer das nicht jetzt möchte, verschiebt die Neugenerierung; wer die offiziellen SDKs benutzt, ist nicht betroffen.