Passa al contenuto principale

Appendix B. HTTP Problems and XML (Problemi HTTP e XML)

Alcune API HTTP utilizzano XML [XML] come formato di contenuto principale. Per questi servizi, può essere utile serializzare i dettagli del problema utilizzando un formato XML compatibile con i vincoli di altri messaggi scambiati.

Il formato XML canonico per i dettagli del problema è un documento XML che identifica il tipo di media "application/problem+xml".

La sua radice del documento è "problem", che utilizza lo spazio dei nomi "urn:ietf:rfc:9457".

Ad esempio, un problema HTTP serializzato in JSON come:

{
 "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"]
}

apparirebbe così in XML:

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:9457">
  <type>https://example.com/probs/out-of-credit</type>
  <title>You do not have enough credit.</title>
  <detail>Your current balance is 30, but that costs 50.</detail>
  <instance>/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>/account/12345</i>
    <i>/account/67890</i>
  </accounts>
</problem>

Si noti che questo formato utilizza un elemento generico "<i>" al posto degli elementi di array nominati in JSON. Ciò è dovuto ai vincoli inerenti a XML, dove i nomi degli elementi devono essere nomi XML validi -- che escludono caratteri come spazi, la maggior parte della punteggiatura e cifre all'inizio del nome.

Questo formato XML per i dettagli del problema segue le convenzioni dello schema XML [ISO-19757-2] non normativo presentato qui. Questa sezione presenta anche i mapping tra nomi di membri JSON e nomi di elementi XML, nonché alcune considerazioni aggiuntive.

Ecco lo schema RELAX NG [ISO-19757-2] non normativo:

default namespace ns = "urn:ietf:rfc:9457"

start = problem

problem =
  element problem {
    (  element  type            { xsd:anyURI }?
     & element  title           { xsd:string }?
     & element  detail          { xsd:string }?
     & element  status          { xsd:positiveInteger }?
     & element  instance        { xsd:anyURI }? ),
    anyNsElement
  }

anyNsElement =
  (  element    ns:*  { anyNsElement | text }
   | attribute  *     { text })*

Si noti che l'ordine degli elementi nei dettagli del problema è esplicitamente non specificato. Sebbene XML sia utilizzato in alcune situazioni per trasmettere un ordine di elaborazione (ad es., XSLT [XSLT]), questo generalmente non è il caso per un oggetto di dettagli del problema, poiché tutti i membri dell'oggetto sono opzionali e possono essere elaborati in qualsiasi ordine.

I dettagli del problema possono contenere membri di estensione che non possono essere mappati su XML. Durante la serializzazione, tali membri potrebbero non apparire nel documento XML o potrebbero essere ignorati durante la deserializzazione. Come indicato nella sezione 3.2, i client DEVONO ignorare tutte le estensioni che non riconoscono.

Quando un oggetto di dettagli del problema contiene membri i cui valori JSON non possono essere rappresentati direttamente in XML (ad es., un oggetto JSON), sarà necessario definire mapping specifici per tali valori in un formato XML.

Ultimo aggiornamento il