Zum Hauptinhalt springen

3. Das Problem Details JSON-Objekt

Das kanonische Modell für Problemdetails ist ein JSON [RFC7159] Objekt.

Wenn es als JSON-Dokument serialisiert wird, wird dieses Format mit dem Medientyp application/problem+json identifiziert.

Zum Beispiel eine HTTP-Antwort mit JSON-Problemdetails:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

Hier zeigt das Guthaben-aufgebraucht-Problem (identifiziert durch seinen Typ-URI) in title den Grund für den 403 an, gibt mit instance eine Referenz für das spezifische Problemauftreten, liefert in detail auftretensspezifische Details und fügt zwei Erweiterungen hinzu; balance übermittelt den Kontostand und accounts gibt Links, wo das Konto aufgeladen werden kann.

Die Fähigkeit, problemspezifische Erweiterungen zu übermitteln, ermöglicht es, mehr als ein Problem zu übermitteln. Zum Beispiel:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
                      "name": "age",
                      "reason": "must be a positive integer"
                    },
                    {
                      "name": "color",
                      "reason": "must be 'green', 'red' or 'blue'"}
                  ]
}

Beachten Sie, dass dies erfordert, dass jedes der Teilprobleme ähnlich genug ist, um denselben HTTP-Statuscode zu verwenden. Wenn sie es nicht sind, könnte der Code 207 (Multi-Status) [RFC4918] verwendet werden, um mehrere Statusnachrichten zu kapseln.

3.1. Mitglieder eines Problemdetails-Objekts (Members of a Problem Details Object)​

Ein Problemdetails-Objekt kann die folgenden Mitglieder haben:

  • type (Zeichenkette) - Eine URI-Referenz [RFC3986], die den Problemtyp identifiziert. Diese Spezifikation ermutigt dazu, dass sie bei Dereferenzierung menschenlesbare Dokumentation für den Problemtyp bereitstellt (z.B. unter Verwendung von HTML [W3C.REC-html5-20141028]). Wenn dieses Mitglied nicht vorhanden ist, wird sein Wert als about:blank angenommen.

  • title (Zeichenkette) - Eine kurze, menschenlesbare Zusammenfassung des Problemtyps. Sie sollte sich nicht (SHOULD NOT) von Auftreten zu Auftreten des Problems ändern, außer zu Lokalisierungszwecken (z.B. unter Verwendung proaktiver Inhaltsverhandlung; siehe [RFC7231], Section 3.4).

  • status (Zahl) - Der HTTP-Statuscode ([RFC7231], Section 6), der vom Ursprungsserver für dieses Auftreten des Problems generiert wurde.

  • detail (Zeichenkette) - Eine menschenlesbare Erklärung spezifisch für dieses Auftreten des Problems.

  • instance (Zeichenkette) - Eine URI-Referenz, die das spezifische Auftreten des Problems identifiziert. Sie kann bei Dereferenzierung weitere Informationen liefern oder auch nicht.

Verbraucher müssen (MUST) die type-Zeichenkette als primären Identifikator für den Problemtyp verwenden; die title-Zeichenkette ist beratend und nur für Benutzer enthalten, die die Semantik des URI nicht kennen und nicht die Fähigkeit haben, sie zu entdecken (z.B. Offline-Protokollanalyse). Verbraucher sollten (SHOULD NOT) den Typ-URI nicht automatisch dereferenzieren.

Das status-Mitglied ist, falls vorhanden, nur beratend; es übermittelt den verwendeten HTTP-Statuscode zur Bequemlichkeit des Verbrauchers. Generatoren müssen (MUST) denselben Statuscode in der tatsächlichen HTTP-Antwort verwenden, um sicherzustellen, dass generische HTTP-Software, die dieses Format nicht versteht, sich weiterhin korrekt verhält. Siehe Abschnitt 5 für weitere Vorbehalte bezüglich seiner Verwendung.

Verbraucher können das status-Mitglied verwenden, um zu bestimmen, welcher ursprüngliche Statuscode vom Generator verwendet wurde, in Fällen, in denen er geändert wurde (z.B. durch einen Vermittler oder Cache), und wenn Nachrichtenkörper ohne HTTP-Informationen persistent bleiben. Generische HTTP-Software wird weiterhin den HTTP-Statuscode verwenden.

Das detail-Mitglied sollte, falls vorhanden, sich darauf konzentrieren, dem Client bei der Behebung des Problems zu helfen, anstatt Debugging-Informationen bereitzustellen.

Verbraucher sollten (SHOULD NOT) das detail-Mitglied nicht nach Informationen parsen; Erweiterungen sind geeignetere und weniger fehleranfällige Wege, um solche Informationen zu erhalten.

Beachten Sie, dass sowohl type als auch instance relative URIs akzeptieren; das bedeutet, dass sie relativ zur Basis-URI des Dokuments aufgelöst werden müssen, wie in [RFC3986], Section 5 angegeben.

3.2. Erweiterungsmitglieder (Extension Members)​

Problemtypdefinitionen können (MAY) das Problemdetails-Objekt mit zusätzlichen Mitgliedern erweitern.

Zum Beispiel definiert unser „Guthaben-aufgebraucht"-Problem oben zwei solche Erweiterungen -- balance und accounts, um zusätzliche, problemspezifische Informationen zu übermitteln.

Clients, die Problemdetails konsumieren, müssen (MUST) alle Erweiterungen ignorieren, die sie nicht erkennen; dies ermöglicht es Problemtypen, sich weiterzuentwickeln und in Zukunft zusätzliche Informationen einzuschließen.

Beachten Sie, dass, da Erweiterungen effektiv vom Problemtyp in einen Namensraum gestellt werden, es nicht möglich ist, neue „Standard"-Mitglieder zu definieren, ohne einen neuen Medientyp zu definieren.

Letztes Update am