5. Anfrage/Antwort-Semantik

CoAP arbeitet unter einem ähnlichen Anfrage/Antwort-Modell wie HTTP: Ein CoAP-Endpunkt in der Rolle eines "Client" sendet eine oder mehrere CoAP-Anfragen an einen "Server", der die Anfragen durch Senden von CoAP-Antworten bedient. Anders als bei HTTP werden Anfragen und Antworten nicht über eine zuvor aufgebaute Verbindung gesendet, sondern asynchron über CoAP-Nachrichten ausgetauscht.

5.1. Anfragen

Eine CoAP-Anfrage besteht aus der auf die Ressource anzuwendenden Methode, dem Identifikator der Ressource, einer Nutzlast und einem Internet-Medientyp (falls vorhanden) sowie optionalen Metadaten über die Anfrage.

CoAP unterstützt die grundlegenden Methoden GET, POST, PUT und DELETE, die sich leicht auf HTTP abbilden lassen. Sie haben dieselben Eigenschaften safe (nur Abruf) und idempotent (Sie können sie mehrfach mit denselben Auswirkungen aufrufen) wie HTTP (siehe Abschnitt 9.1 von [RFC2616]). Die Methode GET ist safe; daher darf sie keine andere Aktion an einer Ressource als den Abruf vornehmen (MUST NOT). Die Methoden GET, PUT und DELETE müssen so ausgeführt werden, dass sie idempotent sind (MUST). POST ist nicht idempotent, da seine Wirkung vom Origin-Server bestimmt wird und von der Zielressource abhängt; sie führt üblicherweise dazu, dass eine neue Ressource erstellt oder die Zielressource aktualisiert wird.

Eine Anfrage wird initiiert, indem das Code-Feld im CoAP-Header einer Confirmable- oder Non-confirmable-Nachricht auf einen Method Code gesetzt und Anfrageinformationen aufgenommen werden.

Die in Anfragen verwendeten Methoden werden in Abschnitt 5.8 ausführlich beschrieben.

5.2. Antworten

Nach dem Empfang und der Interpretation einer Anfrage antwortet ein Server mit einer CoAP-Antwort, die über ein vom Client erzeugtes Token mit der Anfrage abgeglichen wird (Abschnitt 5.3); beachten Sie, dass dies anders ist als die Message ID, die eine Confirmable-Nachricht mit ihrer Acknowledgement abgleicht.

Eine Antwort wird dadurch identifiziert, dass das Code-Feld im CoAP-Header auf einen Response Code gesetzt ist. Ähnlich wie der HTTP Status Code zeigt der CoAP Response Code das Ergebnis des Versuchs an, die Anfrage zu verstehen und zu erfüllen. Diese Codes sind in Abschnitt 5.9 vollständig definiert. Die im Code-Feld des CoAP-Headers zu setzenden Response Code-Nummern werden im CoAP Response Code Registry geführt (Abschnitt 12.1.2).

 0
 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|class|  detail |
+-+-+-+-+-+-+-+-+

Abbildung 9: Struktur eines Response Code

Die oberen drei Bits der 8-Bit-Response Code-Nummer definieren die Klasse der Antwort. Die unteren fünf Bits haben keine kategorisierende Rolle; sie liefern zusätzliche Details zur Gesamtklasse (Abbildung 9).

Als menschenlesbare Notation für Spezifikationen und Protokolldiagnosen werden CoAP-Codenummern einschließlich des Response Code im Format "c.dd" dokumentiert, wobei "c" die Klasse in Dezimaldarstellung und "dd" das Detail als zweistellige Dezimalzahl ist. Beispielsweise wird "Forbidden" als 4.03 geschrieben -- was einen 8-Bit-Codewert von hexadezimal 0x83 (40x20+3) oder dezimal 131 (432+3) angibt.

Es gibt 3 Klassen von Response Codes:

2 - Success: Die Anfrage wurde erfolgreich empfangen, verstanden und akzeptiert.

4 - Client Error: Die Anfrage enthält fehlerhafte Syntax oder kann nicht erfüllt werden.

5 - Server Error: Der Server konnte eine offenbar gültige Anfrage nicht erfüllen.

Die Response Codes sind erweiterbar ausgelegt: Response Codes der Klasse Client Error oder Server Error, die von einem Endpunkt nicht erkannt werden, werden als äquivalent zum generischen Response Code dieser Klasse behandelt (4.00 bzw. 5.00). Es gibt jedoch keinen generischen Response Code, der Erfolg anzeigt, sodass ein Response Code der Klasse Success, der von einem Endpunkt nicht erkannt wird, nur dazu verwendet werden kann, festzustellen, dass die Anfrage erfolgreich war, ohne weitere Details.

Die möglichen Response Codes werden in Abschnitt 5.9 ausführlich beschrieben.

Antworten können auf verschiedene Weise gesendet werden, die in den folgenden Unterabschnitten definiert sind.

5.2.1. Piggybacked

Im grundlegendsten Fall wird die Antwort direkt in der Acknowledgement-Nachricht mitgeführt, die die Anfrage bestätigt (was voraussetzt, dass die Anfrage in einer Confirmable-Nachricht mitgeführt wurde). Dies wird als "Piggybacked Response" bezeichnet.

Die Antwort wird in der Acknowledgement-Nachricht zurückgegeben, unabhängig davon, ob die Antwort Erfolg oder Fehler anzeigt. Tatsächlich wird die Antwort auf die Acknowledgement-Nachricht aufgesattelt (piggybacked), und es ist keine separate Nachricht erforderlich, um die Antwort zurückzugeben.

Implementierungshinweis: Das Protokoll überlässt die Entscheidung, ob eine Antwort piggybacked wird oder nicht (d. h. eine separate Antwort gesendet wird), dem Server. Der Client muss darauf vorbereitet sein, beides zu empfangen (MUST). Auf der Ebene der Implementierungsqualität besteht eine starke Erwartung, dass Server Code implementieren, um wann immer möglich piggybacking durchzuführen -- was Ressourcen im Netzwerk sowie beim Client und beim Server spart.

5.2.2. Separate

Es ist nicht in allen Fällen möglich, eine piggybacked Response zurückzugeben. Beispielsweise kann ein Server länger brauchen, um die Repräsentation der angeforderten Ressource zu beschaffen, als er warten kann, um die Acknowledgement-Nachricht zurückzusenden, ohne zu riskieren, dass der Client die Anfragenachricht wiederholt erneut überträgt (siehe auch die Erörterung von PROCESSING_DELAY in Abschnitt 4.8.2). Die Antwort auf eine in einer Non-confirmable-Nachricht mitgeführte Anfrage wird immer separat gesendet (da es keine Acknowledgement-Nachricht gibt).

Eine Möglichkeit, dies in einem Server zu implementieren, besteht darin, den Versuch zu starten, die Ressourcenrepräsentation zu beschaffen, und währenddessen einen Bestätigungstimer ablaufen zu lassen. Ein Server kann auch sofort eine Bestätigung senden, wenn er im Voraus weiß, dass es keine piggybacked Response geben wird. In beiden Fällen ist die Bestätigung faktisch ein Versprechen, dass die Anfrage später bearbeitet wird.

Wenn der Server schließlich die Ressourcenrepräsentation beschafft hat, sendet er die Antwort. Wenn gewünscht wird, dass diese Nachricht nicht verloren geht, wird sie als Confirmable-Nachricht vom Server an den Client gesendet und vom Client mit einer Acknowledgement beantwortet, die die vom Server gewählte neue Message ID wiedergibt. (Sie kann auch als Non-confirmable-Nachricht gesendet werden; siehe Abschnitt 5.2.3.)

Wenn der Server sich für die Verwendung einer separate Response entscheidet, sendet er die Acknowledgement auf die Confirmable-Anfrage als Empty-Nachricht. Sobald der Server eine Empty Acknowledgement zurücksendet, darf er die Antwort nicht in einer anderen Acknowledgement zurücksenden (MUST NOT), selbst wenn der Client eine weitere identische Anfrage erneut überträgt. Wenn eine erneut übertragene Anfrage empfangen wird (vielleicht weil die ursprüngliche Acknowledgement verzögert wurde), wird eine weitere Empty Acknowledgement gesendet, und jede Antwort muss als separate Response gesendet werden (MUST).

Wenn der Server dann eine Confirmable-Antwort sendet, muss die Acknowledgement des Clients auf diese Antwort ebenfalls eine Empty-Nachricht sein (eine, die weder eine Anfrage noch eine Antwort mitführt) (MUST). Der Server muss die erneute Übertragung seiner Antwort bei jeder passenden Acknowledgement (wobei jeglicher Response Code oder Payload stillschweigend ignoriert wird) oder Reset-Nachricht einstellen (MUST).

Implementierungshinweise: Beachten Sie, dass die Confirmable-Nachricht, die die Antwort mitführt, da der zugrunde liegende Datagrammtransport möglicherweise nicht reihenfolgetreu ist, tatsächlich vor oder nach der Acknowledgement-Nachricht für die Anfrage eintreffen kann; für die Zwecke der Beendigung der erneuten Übertragungssequenz dient dies ebenfalls als Bestätigung. Beachten Sie auch, dass das CoAP-Protokoll selbst hier zwar keine spezifischen Anforderungen stellt, aber die Erwartung besteht, dass die Antwort innerhalb eines aus Anwendungssicht angemessenen Zeitrahmens eintrifft. Da es kein zugrunde liegendes Transportprotokoll gibt, das angewiesen werden könnte, einen Keep-alive-Mechanismus auszuführen, möchte der Anforderer möglicherweise einen Timeout einrichten, der nicht mit den erneuten Übertragungstimern von CoAP zusammenhängt, für den Fall, dass der Server zerstört oder anderweitig nicht in der Lage ist, die Antwort zu senden.

5.2.3. Non-confirmable

Wenn die Anfragenachricht Non-confirmable ist, sollte die Antwort ebenfalls in einer Non-confirmable-Nachricht zurückgegeben werden (SHOULD). Ein Endpunkt muss jedoch darauf vorbereitet sein, eine Non-confirmable-Antwort (der eine Empty Acknowledgement-Nachricht vorausgeht oder folgt) als Erwiderung auf eine Confirmable-Anfrage oder eine Confirmable-Antwort als Erwiderung auf eine Non-confirmable-Anfrage zu empfangen (MUST).

5.3. Anfrage/Antwort-Abgleich

Unabhängig davon, wie eine Antwort gesendet wird, wird sie über ein Token, das der Client in die Anfrage aufnimmt, zusammen mit zusätzlichen Adressinformationen des entsprechenden Endpunkts, mit der Anfrage abgeglichen.

5.3.1. Token

Das Token wird verwendet, um eine Antwort einer Anfrage zuzuordnen. Der Token-Wert ist eine Folge von 0 bis 8 Bytes. (Beachten Sie, dass jede Nachricht ein Token mitführt, auch wenn es die Länge null hat.) Jede Anfrage führt ein vom Client erzeugtes Token mit, das der Server in jeder resultierenden Antwort wiedergeben muss (unverändert) (MUST).

Ein Token ist für die Verwendung als clientlokaler Identifikator gedacht, um zwischen gleichzeitigen Anfragen zu unterscheiden (siehe Abschnitt 5.3); es hätte auch "Request ID" genannt werden können.

Der Client sollte Token so erzeugen, dass die für ein gegebenes Quell-/Ziel-Endpunktpaar derzeit verwendeten Token eindeutig sind (SHOULD). (Beachten Sie, dass eine Client-Implementierung dasselbe Token für jede Anfrage verwenden kann, wenn sie jedes Mal einen anderen Endpunkt verwendet, z. B. eine andere Quellportnummer.) Ein leerer Token-Wert ist z. B. dann angemessen, wenn keine anderen Token zu einem Ziel verwendet werden oder wenn Anfragen pro Ziel seriell gestellt werden und piggybacked Responses erhalten. Es gibt jedoch mehrere mögliche Implementierungsstrategien, um dies zu erfüllen.

Ein Client, der eine Anfrage ohne Verwendung von Transport Layer Security (Abschnitt 9) sendet, sollte ein nicht triviales, randomisiertes Token verwenden, um sich gegen Spoofing von Antworten zu schützen (Abschnitt 11.4) (SHOULD). Diese schützende Verwendung von Token ist der Grund dafür, dass sie bis zu 8 Bytes groß sein dürfen. Die tatsächliche Größe der für das Token zu verwendenden Zufallskomponente hängt von den Sicherheitsanforderungen des Clients und dem Grad der Bedrohung durch Spoofing von Antworten ab. Ein Client, der mit dem allgemeinen Internet verbunden ist, sollte mindestens 32 Bits Zufälligkeit verwenden (SHOULD), wobei zu bedenken ist, dass eine fehlende direkte Verbindung zum Internet nicht unbedingt einen ausreichenden Schutz gegen Spoofing darstellt. (Beachten Sie, dass die Message ID nur wenig Schutz bietet, da sie üblicherweise sequenziell vergeben, d. h. erratbar, ist und durch Spoofing einer separate Response umgangen werden kann.) Clients, die die Token-Länge optimieren möchten, möchten möglicherweise zusätzlich den Grad laufender Angriffe erkennen (z. B. durch Zählen kürzlicher Token-Fehlpaarungen in eingehenden Nachrichten) und die Token-Länge entsprechend nach oben anpassen. [RFC4086] erörtert Anforderungen an Zufälligkeit für die Sicherheit.

Ein Endpunkt, der ein Token empfängt, das er nicht erzeugt hat, muss das Token als opak behandeln und keine Annahmen über dessen Inhalt oder Struktur treffen (MUST).

5.3.2. Regeln für den Anfrage/Antwort-Abgleich

Die genauen Regeln für den Abgleich einer Antwort mit einer Anfrage lauten wie folgt:

1. Der Quellendpunkt der Antwort muss derselbe sein wie der Zielendpunkt der ursprünglichen Anfrage (MUST).

2. Bei einer piggybacked Response müssen die Message ID der Confirmable-Anfrage und der Acknowledgement übereinstimmen, und die Token der Antwort und der ursprünglichen Anfrage müssen übereinstimmen (MUST). Bei einer separate Response müssen nur die Token der Antwort und der ursprünglichen Anfrage übereinstimmen (MUST).

Falls eine Nachricht, die eine Antwort mitführt, unerwartet ist (der Client wartet nicht auf eine Antwort vom identifizierten Endpunkt, an der adressierten Endpunktadresse und/oder mit dem gegebenen Token), wird die Antwort zurückgewiesen (Abschnitte 4.2 und 4.3).

Implementierungshinweis: Ein Client, der eine Antwort in einer CON-Nachricht empfängt, möchte möglicherweise den Nachrichtenzustand direkt nach dem Senden der ACK aufräumen. Wenn diese ACK verloren geht und der Server die CON erneut überträgt, hat der Client möglicherweise keinen Zustand mehr, dem er diese Antwort zuordnen kann, wodurch die erneute Übertragung zu einer unerwarteten Nachricht wird; der Client wird wahrscheinlich eine Reset-Nachricht senden, damit er keine weiteren erneuten Übertragungen empfängt. Dieses Verhalten ist normal und kein Hinweis auf einen Fehler. (Clients, die ihren Zustandsspeicher nicht aggressiv optimieren, haben weiterhin Nachrichtenzustand, der die zweite CON als erneute Übertragung identifiziert. Clients, die tatsächlich weitere Nachrichten vom Server erwarten [OBSERVE], müssen ohnehin Zustand behalten.)

5.4. Optionen

Sowohl Anfragen als auch Antworten können eine Liste mit einer oder mehreren Optionen enthalten. Beispielsweise wird der URI in einer Anfrage in mehreren Optionen transportiert, und Metadaten, die in HTTP in einem HTTP-Header mitgeführt würden, werden ebenfalls als Optionen bereitgestellt.

CoAP definiert einen einzigen Satz von Optionen, die sowohl in Anfragen als auch in Antworten verwendet werden:

• Content-Format

• ETag

• Location-Path

• Location-Query

• Max-Age

• Proxy-Uri

• Proxy-Scheme

• Uri-Host

• Uri-Path

• Uri-Port

• Uri-Query

• Accept

• If-Match

• If-None-Match

• Size1

Die Semantik dieser Optionen zusammen mit ihren Eigenschaften ist in Abschnitt 5.10 ausführlich definiert.

Nicht alle Optionen sind für die Verwendung mit allen Methoden und Response Codes definiert. Die möglichen Optionen für Methoden und Response Codes sind in Abschnitt 5.8 bzw. 5.9 definiert. Falls eine Option nicht für eine Methode oder einen Response Code definiert ist, darf sie von einem Sender nicht aufgenommen werden (MUST NOT) und muss von einem Empfänger wie eine nicht erkannte Option behandelt werden (MUST).

5.4.1. Critical/Elective

Optionen fallen in eine von zwei Klassen: "critical" oder "elective". Der Unterschied zwischen ihnen besteht darin, wie eine von einem Endpunkt nicht erkannte Option behandelt wird:

• Beim Empfang müssen nicht erkannte Optionen der Klasse "elective" stillschweigend ignoriert werden (MUST).

• Nicht erkannte Optionen der Klasse "critical", die in einer Confirmable-Anfrage auftreten, müssen die Rückgabe einer 4.02 (Bad Option)-Antwort bewirken (MUST). Diese Antwort sollte eine Diagnosenutzlast enthalten, die die nicht erkannte(n) Option(en) beschreibt (siehe Abschnitt 5.5.2) (SHOULD).

• Nicht erkannte Optionen der Klasse "critical", die in einer Confirmable-Antwort auftreten oder in einer Acknowledgement piggybacked sind, müssen die Zurückweisung der Antwort bewirken (Abschnitt 4.2) (MUST).

• Nicht erkannte Optionen der Klasse "critical", die in einer Non-confirmable-Nachricht auftreten, müssen die Zurückweisung der Nachricht bewirken (Abschnitt 4.3) (MUST).

Beachten Sie, dass eine Option, ob critical oder elective, niemals "obligatorisch" ist (sie ist immer optional): Diese Regeln sind definiert, um Implementierungen zu ermöglichen, die Verarbeitung von Optionen zu beenden, die sie nicht verstehen oder nicht implementieren.

Critical/Elective-Regeln gelten für nicht proxyende Endpunkte. Ein Proxy verarbeitet Optionen anhand der Klassen Unsafe/Safe-to-Forward, wie in Abschnitt 5.7 definiert.

5.4.2. Proxy Unsafe oder Safe-to-Forward und NoCacheKey

Zusätzlich dazu, dass eine Option als critical oder elective gekennzeichnet ist, werden Optionen auch danach klassifiziert, wie ein Proxy mit der Option umgehen soll, wenn er sie nicht erkennt. Zu diesem Zweck kann eine Option entweder als Unsafe to forward (UnSafe ist gesetzt) oder als Safe-to-Forward (UnSafe ist nicht gesetzt) betrachtet werden.

Darüber hinaus gibt die Optionsnummer bei einer Option, die als Safe-to-Forward gekennzeichnet ist, an, ob sie in einer Anfrage als Teil des Cache-Key vorgesehen ist (Abschnitt 5.6). Wenn einige der NoCacheKey-Bits 0 sind, ist sie es; wenn alle NoCacheKey-Bits 1 sind, ist sie es nicht (siehe Abschnitt 5.4.6).

Hinweis: Die Cache-Key-Angabe ist nur für Proxys relevant, die die gegebene Option nicht als Anfrageoption implementieren und stattdessen nur auf die Unsafe/Safe-to-Forward-Angabe vertrauen. Beispielsweise ist es für ETag grob ineffizient, die Anfrageoption tatsächlich als Teil des Cache-Key zu verwenden, aber es ist das Beste, was man tun kann, wenn ETag nicht von einem Proxy implementiert wird, da sich die Antwort je nach Vorhandensein der Anfrageoption unterscheidet. Ein nützlicherer Proxy, der die ETag-Anfrageoption tatsächlich implementiert, verwendet ETag nicht als Teil des Cache-Key.

NoCacheKey wird in drei Bits angegeben, sodass nur einer von acht Codepunkten als NoCacheKey qualifiziert ist und sieben von acht Codepunkten für den offenbar wahrscheinlicheren Fall übrig bleiben.

Das Proxy-Verhalten in Bezug auf diese Klassen ist in Abschnitt 5.7 definiert.

5.4.3. Länge

Optionswerte sind mit einer bestimmten Länge definiert, oft in Form einer Ober- und Untergrenze. Wenn die Länge eines Optionswerts in einer Anfrage außerhalb des definierten Bereichs liegt, muss diese Option wie eine nicht erkannte Option behandelt werden (siehe Abschnitt 5.4.1) (MUST).

5.4.4. Standardwerte

Optionen können mit einem Standardwert definiert sein. Wenn der Wert einer Option dieser Standardwert sein soll, sollte die Option nicht in die Nachricht aufgenommen werden (SHOULD NOT). Wenn die Option nicht vorhanden ist, muss der Standardwert angenommen werden (MUST).

Wenn eine kritische Option einen Standardwert hat, ist dieser so gewählt, dass das Fehlen der Option in einer Nachricht sowohl von Implementierungen, die die kritische Option nicht kennen, als auch von Implementierungen, die dieses Fehlen als Vorhandensein des Standardwerts der Option interpretieren, korrekt verarbeitet werden kann.

5.4.5. Wiederholbare Optionen

Die Definition einiger Optionen legt fest, dass diese Optionen wiederholbar sind. Eine Option, die wiederholbar ist, kann ein- oder mehrmals in eine Nachricht aufgenommen werden (MAY). Eine Option, die nicht wiederholbar ist, darf nicht mehr als einmal in eine Nachricht aufgenommen werden (MUST NOT).

Wenn eine Nachricht eine Option mit mehr Vorkommen enthält, als für die Option definiert sind, muss jedes überzählige Optionsvorkommen, das anschließend in der Nachricht erscheint, wie eine nicht erkannte Option behandelt werden (siehe Abschnitt 5.4.1) (MUST).

5.4.6. Optionsnummern

Eine Option wird durch eine Optionsnummer identifiziert, die auch einige zusätzliche Semantikinformationen liefert, z. B. zeigen ungerade Nummern eine kritische Option an, während gerade Nummern eine elektive Option anzeigen. Beachten Sie, dass dies nicht nur eine Konvention ist, sondern ein Merkmal des Protokolls: Ob eine Option elektiv oder kritisch ist, wird vollständig dadurch bestimmt, ob ihre Optionsnummer gerade oder ungerade ist.

Allgemeiner ausgedrückt wird eine Optionsnummer mit einer Bitmaske konstruiert, die angibt, ob eine Option Critical oder Elective, Unsafe oder Safe-to-Forward ist und, im Fall von Safe-to-Forward, eine Cache-Key-Angabe liefert, wie in der folgenden Abbildung dargestellt. Im folgenden Text wird die Bitmaske als ein einzelnes Byte ausgedrückt, das auf das niedrigstwertige Byte der Optionsnummer in unsigned-Integer-Darstellung angewendet wird. Wenn Bit 7 (das niedrigstwertige Bit) 1 ist, ist eine Option Critical (und entsprechend Elective, wenn 0). Wenn Bit 6 1 ist, ist eine Option Unsafe (und entsprechend Safe-to-Forward, wenn 0). Wenn Bit 6 0 ist, d. h. die Option nicht Unsafe ist, ist sie genau dann kein Cache-Key (NoCacheKey), wenn die Bits 3-5 alle auf 1 gesetzt sind; alle anderen Bitkombinationen bedeuten, dass sie tatsächlich ein Cache-Key ist. Diese Optionsklassen werden in den nächsten Abschnitten erläutert.

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
|           | NoCacheKey| U | C |
+---+---+---+---+---+---+---+---+

Abbildung 10: Optionsnummernmaske (niedrigstwertiges Byte)

Ein Endpunkt kann ein Äquivalent des C-Codes in Abbildung 11 verwenden, um die Eigenschaften einer Optionsnummer "onum" abzuleiten.

Critical = (onum & 1);
UnSafe = (onum & 2);
NoCacheKey = ((onum & 0x1e) == 0x1c);

Abbildung 11: Bestimmung der Eigenschaften aus einer Optionsnummer

Die Optionsnummern für die in diesem Dokument definierten Optionen sind im Register "CoAP Option Numbers" aufgeführt (Abschnitt 12.2).

5.5. Nutzlasten und Repräsentationen

Sowohl Anfragen als auch Antworten können je nach Methode bzw. Response Code eine Nutzlast enthalten. Wenn für eine Methode oder einen Response Code keine Nutzlast definiert ist, darf ein Sender keine aufnehmen (MUST NOT), und ein Empfänger muss sie ignorieren (MUST).

5.5.1. Representation

Die Nutzlast von Anfragen oder von Antworten, die Erfolg anzeigen, ist typischerweise eine Repräsentation einer Ressource ("resource representation") oder das Ergebnis der angeforderten Aktion ("action result"). Ihr Format wird durch den Internet-Medientyp und das Content-Coding angegeben, die durch die Content-Format-Option gegeben sind. In Abwesenheit dieser Option wird kein Standardwert angenommen, und das Format muss von der Anwendung abgeleitet werden (z. B. aus dem Anwendungskontext). Nutzlast-"Sniffing" sollte nur versucht werden, wenn kein Inhaltstyp angegeben ist (SHOULD).

Implementierungshinweis: Auf der Ebene der Implementierungsqualität besteht eine starke Erwartung, dass wann immer möglich eine Content-Format-Angabe zusammen mit Ressourcenrepräsentationen bereitgestellt wird. Dies ist nicht allein deshalb eine Anforderung der Stufe "SHOULD", weil es keine Protokollanforderung ist und es auch schwierig wäre, genau darzulegen, in welchen Fällen diese Erwartung verletzt werden kann.

Bei Antworten, die einen Client- oder Serverfehler anzeigen, wird die Nutzlast nur dann als Repräsentation des Ergebnisses der angeforderten Aktion betrachtet, wenn eine Content-Format-Option angegeben ist. In Abwesenheit dieser Option ist die Nutzlast eine Diagnosenutzlast (Abschnitt 5.5.2).

5.5.2. Diagnostic Payload

Wenn keine Content-Format-Option angegeben ist, ist die Nutzlast von Antworten, die einen Client- oder Serverfehler anzeigen, eine kurze, für Menschen lesbare Diagnosenachricht, die die Fehlersituation erläutert. Diese Diagnosenachricht muss unter Verwendung von UTF-8 [RFC3629] kodiert werden (MUST), genauer unter Verwendung der Net-Unicode-Form [RFC5198].

Die Nachricht ähnelt der Reason-Phrase in einer HTTP-Statuszeile. Sie ist nicht für Endbenutzer gedacht, sondern für Softwareentwickler, die sie beim Debuggen im Kontext der vorliegenden englischsprachigen Spezifikation interpretieren müssen; daher ist kein Mechanismus für Sprachkennzeichnung erforderlich oder vorgesehen. Anders als in HTTP üblich, sollte die Nutzlast leer sein, wenn es keine zusätzlichen Informationen über den Response Code hinaus gibt (SHOULD).

5.5.3. Selected Representation

Nicht alle Antworten führen eine Nutzlast mit, die eine Repräsentation der durch die Anfrage adressierten Ressource bereitstellt. Es ist jedoch manchmal nützlich, eine solche Repräsentation in Bezug auf eine Antwort referenzieren zu können, unabhängig davon, ob sie tatsächlich beigefügt war.

Wir verwenden den Begriff "selected representation", um die aktuelle Repräsentation einer Zielressource zu bezeichnen, die in einer erfolgreichen Antwort ausgewählt worden wäre, wenn die entsprechende Anfrage die Methode GET verwendet und alle bedingten Anfrageoptionen ausgeschlossen hätte (Abschnitt 5.10.8).

Bestimmte Antwortoptionen liefern Metadaten über die selected representation, die bei Antworten auf einige zustandsändernde Methoden von der in der Nachricht enthaltenen Repräsentation abweichen können. Von den in dieser Spezifikation definierten Antwortoptionen ist nur die ETag-Antwortoption (Abschnitt 5.10.6) als Metadaten über die selected representation definiert.

5.5.4. Content Negotiation

Ein Server kann in der Lage sein, eine Repräsentation für eine Ressource in einem von mehreren Repräsentationsformaten bereitzustellen. Ohne weitere Informationen vom Client wird er die Repräsentation in dem Format bereitstellen, das er bevorzugt.

Durch Verwendung der Accept-Option (Abschnitt 5.10.4) in einer Anfrage kann der Client angeben, welches Content-Format er zu empfangen bevorzugt.

5.6. Caching

CoAP-Endpunkte können Antworten zwischenspeichern, um die Antwortzeit und den Verbrauch an Netzwerkbandbreite bei zukünftigen, gleichwertigen Anfragen zu reduzieren (MAY).

Das Ziel des Caching in CoAP ist es, eine frühere Antwortnachricht wiederzuverwenden, um eine aktuelle Anfrage zu erfüllen. In einigen Fällen kann eine gespeicherte Antwort ohne die Notwendigkeit einer Netzwerkanfrage wiederverwendet werden, was Latenz und Netzwerk-Roundtrips reduziert; zu diesem Zweck wird ein "Freshness"-Mechanismus verwendet (siehe Abschnitt 5.6.1). Selbst wenn eine neue Anfrage erforderlich ist, ist es oft möglich, die Nutzlast einer früheren Antwort wiederzuverwenden, um die Anfrage zu erfüllen, wodurch die Nutzung der Netzwerkbandbreite reduziert wird; zu diesem Zweck wird ein "Validierungs"-Mechanismus verwendet (siehe Abschnitt 5.6.2).

Anders als bei HTTP hängt die Cachefähigkeit von CoAP-Antworten nicht von der Anfragemethode ab, sondern vom Response Code. Die Cachefähigkeit jedes Response Code ist zusammen mit den Response Code-Definitionen in Abschnitt 5.9 definiert. Response Codes, die Erfolg anzeigen und von einem Endpunkt nicht erkannt werden, dürfen nicht zwischengespeichert werden (MUST NOT).

Für eine vorgelegte Anfrage darf ein CoAP-Endpunkt eine gespeicherte Antwort nicht verwenden (MUST NOT), es sei denn:

• die vorgelegte Anfragemethode und die zum Erhalt der gespeicherten Antwort verwendete stimmen überein,

• alle Optionen stimmen zwischen denen in der vorgelegten Anfrage und denen der zum Erhalt der gespeicherten Antwort verwendeten Anfrage überein (was die Anfrage-URI einschließt), mit der Ausnahme, dass keine Übereinstimmung für Anfrageoptionen erforderlich ist, die als NoCacheKey gekennzeichnet sind (Abschnitt 5.4) oder vom Cache erkannt und in Bezug auf ihr spezifiziertes Cache-Verhalten vollständig interpretiert werden (wie die in Abschnitt 5.10.6 beschriebene ETag-Anfrageoption; siehe auch Abschnitt 5.4.2), und

• die gespeicherte Antwort entweder frisch oder wie unten definiert erfolgreich validiert ist.

Die Menge der Anfrageoptionen, die zum Abgleich des Cache-Eintrags verwendet wird, wird zusammenfassend auch als "Cache-Key" bezeichnet. Für andere URI-Schemas als coap und coaps kann der Abgleich der Optionen, die die Anfrage-URI bilden, nach für das URI-Schema spezifischen Regeln durchgeführt werden.

5.6.1. Freshness Model

Wenn eine Antwort im Cache "frisch" ist, kann sie verwendet werden, um nachfolgende Anfragen zu erfüllen, ohne den Origin-Server zu kontaktieren, wodurch die Effizienz verbessert wird.

Der Mechanismus zur Bestimmung der Freshness besteht darin, dass ein Origin-Server mithilfe der Max-Age-Option eine explizite Ablaufzeit in der Zukunft angibt (siehe Abschnitt 5.10.5). Die Max-Age-Option gibt an, dass die Antwort als nicht frisch zu betrachten ist, nachdem ihr Alter größer als die angegebene Anzahl von Sekunden ist.

Die Max-Age-Option hat den Standardwert 60. Wenn sie also in einer cachefähigen Antwort nicht vorhanden ist, gilt die Antwort als nicht frisch, nachdem ihr Alter größer als 60 Sekunden ist. Wenn ein Origin-Server das Caching verhindern möchte, muss er ausdrücklich eine Max-Age-Option mit dem Wert null Sekunden aufnehmen (MUST).

Wenn ein Client eine frische gespeicherte Antwort hat und eine neue Anfrage stellt, die mit der Anfrage für diese gespeicherte Antwort übereinstimmt, macht die neue Antwort die alte Antwort ungültig.

5.6.2. Validation Model

Wenn ein Endpunkt eine oder mehrere gespeicherte Antworten für eine GET-Anfrage hat, aber keine davon verwenden kann (z. B. weil sie nicht frisch sind), kann er die ETag-Option (Abschnitt 5.10.6) in der GET-Anfrage verwenden, um dem Origin-Server sowohl die Möglichkeit zu geben, eine zu verwendende gespeicherte Antwort auszuwählen, als auch deren Freshness zu aktualisieren. Dieser Vorgang wird als "Validieren" oder "Revalidieren" der gespeicherten Antwort bezeichnet.

Beim Senden einer solchen Anfrage sollte der Endpunkt eine ETag-Option hinzufügen, die das Entity-Tag jeder anwendbaren gespeicherten Antwort angibt (SHOULD).

Eine 2.03 (Valid)-Antwort zeigt an, dass die durch das in der ETag-Option der Antwort angegebene Entity-Tag identifizierte gespeicherte Antwort wiederverwendet werden kann, nachdem sie wie in Abschnitt 5.9.1.3 beschrieben aktualisiert wurde.

Jeder andere Response Code zeigt an, dass keine der in der Anfrage nominierten gespeicherten Antworten geeignet ist. Stattdessen sollte die Antwort verwendet werden, um die Anfrage zu erfüllen, und sie kann die gespeicherte Antwort ersetzen (SHOULD bzw. MAY).

5.7. Proxying

Ein Proxy ist ein CoAP-Endpunkt, dem von CoAP-Clients die Aufgabe übertragen werden kann, Anfragen in ihrem Namen auszuführen. Dies kann beispielsweise nützlich sein, wenn die Anfrage andernfalls nicht gestellt werden könnte, oder um die Antwort aus einem Cache zu bedienen, um Antwortzeit und Netzwerkbandbreite oder Energieverbrauch zu reduzieren.

In einer Gesamtarchitektur für eine Constrained RESTful Environment können Proxys recht unterschiedliche Zwecke erfüllen. Proxys können von Clients ausdrücklich ausgewählt werden, eine Rolle, die wir "forward-proxy" nennen. Proxys können auch eingefügt werden, um Origin-Server zu vertreten, eine Rolle, die wir "reverse-proxy" nennen. Orthogonal zu dieser Unterscheidung kann ein Proxy von einer CoAP-Anfrage auf eine CoAP-Anfrage abbilden (CoAP-to-CoAP-Proxy) oder von einem anderen Protokoll übersetzen oder in ein solches ("cross-proxy"). Vollständige Definitionen dieser Begriffe finden sich in Abschnitt 1.2.

Hinweise: Die Terminologie in dieser Spezifikation wurde so gewählt, dass sie kulturell mit der in den weiteren Webanwendungsumgebungen verwendeten Terminologie kompatibel ist, ohne notwendigerweise in jedem Detail übereinzustimmen (was für Constrained RESTful Environments möglicherweise nicht einmal relevant ist). Den Bestandteilen der Begriffe (wie "forward", "reverse" oder "cross") sollte nicht zu viel Semantik zugeschrieben werden.

HTTP-Proxys bieten neben ihrer Funktion als HTTP-Proxys oft eine Transportprotokoll-Proxyfunktion ("CONNECT") an, um Ende-zu-Ende-Transportschichtensicherheit durch den Proxy zu ermöglichen. Für CoAP-to-CoAP-Proxys ist in dieser Spezifikation keine solche Funktion definiert, da die Weiterleitung von UDP-Paketen in Constrained RESTful Environments wahrscheinlich von geringem Wert ist. Siehe auch Abschnitt 10.2.7 für den Fall des cross-proxy.

Wenn ein Client einen Proxy verwendet, um eine Anfrage zu stellen, die ein sicheres URI-Schema verwendet (z. B. "coaps" oder "https"), sollte die Anfrage an den Proxy unter Verwendung von DTLS gesendet werden (SHOULD), außer wenn eine gleichwertige Sicherheit auf niedrigeren Schichten für den Abschnitt zwischen Client und Proxy verwendet wird.

5.7.1. Proxy Operation

Ein Proxy benötigt im Allgemeinen eine Möglichkeit, potenzielle Anfrageparameter für eine Anfrage zu bestimmen, die er an ein Ziel stellt, basierend auf der Anfrage, die er von seinem Client empfangen hat. Diese Möglichkeit ist für einen forward-proxy vollständig spezifiziert, kann aber für einen reverse-proxy von der spezifischen Konfiguration abhängen. Insbesondere gibt der Client eines reverse-proxy im Allgemeinen keinen Locator für das Ziel an, was eine Form der Namespace-Übersetzung im reverse-proxy erforderlich macht. Einige Aspekte der Funktionsweise von Proxys sind jedoch allen ihren Formen gemeinsam.

Wenn ein Proxy keinen Cache verwendet, leitet er die übersetzte Anfrage einfach an das bestimmte Ziel weiter. Andernfalls, wenn er einen Cache verwendet, aber keine gespeicherte Antwort hat, die zur übersetzten Anfrage passt und als frisch gilt, muss er seinen Cache gemäß Abschnitt 5.6 auffrischen. Für Optionen in der Anfrage, die der Proxy erkennt, weiß er, ob die Option als Teil des Schlüssels wirken soll, der beim Nachschlagen des zwischengespeicherten Werts verwendet wird, oder nicht. Da beispielsweise Anfragen für unterschiedliche Uri-Path-Werte unterschiedliche Ressourcen adressieren, sind Uri-Path-Werte immer Teil des Cache-Key, während z. B. Token-Werte niemals Teil des Cache-Key sind. Für Optionen, die der Proxy nicht erkennt, die aber in der Optionsnummer als Safe-to-Forward gekennzeichnet sind, gibt die Option ebenfalls an, ob sie in den Cache-Key aufzunehmen ist (NoCacheKey ist nicht vollständig gesetzt) oder nicht (NoCacheKey ist vollständig gesetzt). (Optionen, die nicht erkannt und als Unsafe gekennzeichnet sind, führen zu 4.02 Bad Option.)

Wenn die Anfrage an das Ziel zeitlich überschritten wird, muss eine 5.04 (Gateway Timeout)-Antwort zurückgegeben werden (MUST). Wenn die Anfrage an das Ziel eine Antwort zurückgibt, die vom Proxy nicht verarbeitet werden kann (z. B. aufgrund nicht erkannter kritischer Optionen oder Nachrichtenformfehler), muss eine 5.02 (Bad Gateway)-Antwort zurückgegeben werden (MUST). Andernfalls gibt der Proxy die Antwort an den Client zurück.

Wenn eine Antwort aus einem Cache erzeugt wird, darf die erzeugte (oder implizierte) Max-Age-Option die ursprünglich vom Server festgelegte max-age nicht verlängern (MUST NOT), wobei die Zeit berücksichtigt wird, die die Ressourcenrepräsentation im Cache verbracht hat. Beispielsweise könnte die Max-Age-Option vom Proxy für jede Antwort mithilfe der Formel angepasst werden:

proxy-max-age = original-max-age - cache-age

Wenn beispielsweise eine Anfrage an eine proxied Ressource gestellt wird, die vor 20 Sekunden aufgefrischt wurde und eine ursprüngliche Max-Age von 60 Sekunden hatte, beträgt die proxied max-age dieser Ressource nun 40 Sekunden. In Anbetracht möglicher Netzwerkverzögerungen auf dem Weg vom Origin-Server sollte ein Proxy bei den angebotenen max-age-Werten konservativ sein.

Alle in einer Proxy-Anfrage vorhandenen Optionen müssen am Proxy verarbeitet werden (MUST). Unsafe-Optionen in einer Anfrage, die vom Proxy nicht erkannt werden, müssen dazu führen, dass der Proxy eine 4.02 (Bad Option)-Antwort zurückgibt (MUST). Ein CoAP-to-CoAP-Proxy muss alle Safe-to-Forward-Optionen, die er nicht erkennt, an den Origin-Server weiterleiten (MUST). Ebenso müssen Unsafe-Optionen in einer Antwort, die vom CoAP-to-CoAP-Proxy-Server nicht erkannt werden, zu einer 5.02 (Bad Gateway)-Antwort führen (MUST). Auch hier müssen nicht erkannte Safe-to-Forward-Optionen weitergeleitet werden (MUST).

Zusätzliche Überlegungen zum Cross-Protocol-Proxying zwischen CoAP und HTTP werden in Abschnitt 10 erörtert.

5.7.2. Forward-Proxies

CoAP unterscheidet zwischen Anfragen, die (so als ob) an einen Origin-Server gestellt werden, und Anfragen, die über einen forward-proxy gestellt werden. CoAP-Anfragen an einen forward-proxy werden als normale Confirmable- oder Non-confirmable-Anfragen an den forward-proxy-Endpunkt gestellt, aber sie geben die Anfrage-URI auf andere Weise an: Die Anfrage-URI in einer Proxy-Anfrage wird als Zeichenkette in der Proxy-Uri-Option angegeben (siehe Abschnitt 5.10.2), während die Anfrage-URI in einer Anfrage an einen Origin-Server in die Optionen Uri-Host, Uri-Port, Uri-Path und Uri-Query aufgeteilt wird (siehe Abschnitt 5.10.1). Alternativ kann die URI in einer Proxy-Anfrage aus einer Proxy-Scheme-Option und den genannten aufgeteilten Optionen zusammengesetzt werden.

Wenn eine Proxy-Anfrage an einen Endpunkt gestellt wird und der Endpunkt nicht bereit oder nicht in der Lage ist, als Proxy für die Anfrage-URI zu fungieren, muss er eine 5.05 (Proxying Not Supported)-Antwort zurückgeben (MUST). Wenn die Authority (Host und Port) als den Proxy-Endpunkt selbst identifizierend erkannt wird (siehe Abschnitt 5.10.2), muss die Anfrage als lokale (nicht proxyte) Anfrage behandelt werden (MUST).

Sofern ein Proxy nicht dafür konfiguriert ist, die Proxy-Anfrage an einen anderen Proxy weiterzuleiten, muss er die Anfrage wie folgt übersetzen (MUST): Das Schema der Anfrage-URI definiert das ausgehende Protokoll und seine Details (z. B. wird CoAP für das Schema "coap" über UDP und für das Schema "coaps" über DTLS verwendet). Für einen CoAP-to-CoAP-Proxy werden die IP-Adresse und der Port des Origin-Servers durch die Authority-Komponente der Anfrage-URI bestimmt, und die Anfrage-URI wird dekodiert und in die Optionen Uri-Host, Uri-Port, Uri-Path und Uri-Query aufgeteilt. Dies verbraucht die Proxy-Uri- oder Proxy-Scheme-Option, die daher nicht an den Origin-Server weitergeleitet wird.

5.7.3. Reverse-Proxies

Reverse-Proxies nutzen die Optionen Proxy-Uri oder Proxy-Scheme nicht, müssen aber das Ziel (den nächsten Hop) einer Anfrage aus Informationen in der Anfrage und Informationen in ihrer Konfiguration bestimmen. Beispielsweise könnte ein reverse-proxy verschiedene Ressourcen anbieten, als wären es seine eigenen Ressourcen, nachdem er durch Ressourcenerkennung von ihrer Existenz erfahren hat. Dem reverse-proxy steht es frei, einen Namespace für die URIs aufzubauen, die diese Ressourcen identifizieren. Ein reverse-proxy kann auch einen Namespace aufbauen, der dem Client mehr Kontrolle darüber gibt, wohin die Anfrage geht, z. B. indem er Host-Identifikatoren und Portnummern in den URI-Pfad der angebotenen Ressourcen einbettet.

Bei der Verarbeitung der Antwort muss ein reverse-proxy darauf achten, dass ETag-Optionswerte aus verschiedenen Quellen nicht bei einer seinen Clients angebotenen Ressource vermischt werden. In vielen Fällen kann das ETag unverändert weitergeleitet werden. Wenn die Abbildung von einer vom reverse-proxy angebotenen Ressource auf Ressourcen, die von seinen verschiedenen Origin-Servern angeboten werden, nicht eindeutig ist, muss der reverse-proxy möglicherweise ein neues ETag erzeugen und dabei sicherstellen, dass die Semantik dieser Option ordnungsgemäß erhalten bleibt.

5.8. Methodendefinitionen

In diesem Abschnitt wird jede Methode zusammen mit ihrem Verhalten definiert. Eine Anfrage mit einem nicht erkannten oder nicht unterstützten Method Code muss eine piggybacked 4.05 (Method Not Allowed)-Antwort erzeugen (MUST).

5.8.1. GET

Die Methode GET ruft eine Repräsentation für die Informationen ab, die derzeit der durch die Anfrage-URI identifizierten Ressource entsprechen. Wenn die Anfrage eine Accept-Option enthält, gibt diese das bevorzugte Content-Format einer Antwort an. Wenn die Anfrage eine ETag-Option enthält, fordert die Methode GET, dass dieses ETag validiert und die Repräsentation nur übertragen wird, wenn die Validierung fehlgeschlagen ist. Bei Erfolg sollte ein Response Code 2.05 (Content) oder 2.03 (Valid) in der Antwort vorhanden sein (SHOULD).

Die Methode GET ist safe und idempotent.

5.8.2. POST

Die Methode POST fordert, dass die in der Anfrage enthaltene Repräsentation verarbeitet wird. Die tatsächliche von der Methode POST ausgeführte Funktion wird vom Origin-Server bestimmt und hängt von der Zielressource ab. Sie führt üblicherweise dazu, dass eine neue Ressource erstellt oder die Zielressource aktualisiert wird.

Wenn auf dem Server eine Ressource erstellt wurde, sollte die vom Server zurückgegebene Antwort einen Response Code 2.01 (Created) haben (SHOULD) und sollte die URI der neuen Ressource in einer Folge von einer oder mehreren Location-Path- und/oder Location-Query-Optionen enthalten (Abschnitt 5.10.7) (SHOULD). Wenn POST erfolgreich ist, aber nicht dazu führt, dass eine neue Ressource auf dem Server erstellt wird, sollte die Antwort einen Response Code 2.04 (Changed) haben (SHOULD). Wenn POST erfolgreich ist und dazu führt, dass die Zielressource gelöscht wird, sollte die Antwort einen Response Code 2.02 (Deleted) haben (SHOULD). POST ist weder safe noch idempotent.

5.8.3. PUT

Die Methode PUT fordert, dass die durch die Anfrage-URI identifizierte Ressource mit der enthaltenen Repräsentation aktualisiert oder erstellt wird. Das Repräsentationsformat wird durch den Medientyp und das Content-Coding angegeben, die in der Content-Format-Option angegeben sind, falls vorhanden.

Wenn am Anfrage-URI eine Ressource existiert, sollte die enthaltene Repräsentation als eine geänderte Version dieser Ressource betrachtet werden (SHOULD), und es sollte ein Response Code 2.04 (Changed) zurückgegeben werden (SHOULD). Wenn keine Ressource existiert, kann der Server eine neue Ressource mit dieser URI erstellen (MAY), was zu einem Response Code 2.01 (Created) führt. Wenn die Ressource nicht erstellt oder geändert werden konnte, sollte ein geeigneter Fehler-Response Code gesendet werden (SHOULD).

Weitere Einschränkungen für ein PUT können durch Aufnahme der Optionen If-Match (siehe Abschnitt 5.10.8.1) oder If-None-Match (siehe Abschnitt 5.10.8.2) in die Anfrage vorgenommen werden.

PUT ist nicht safe, aber idempotent.

5.8.4. DELETE

Die Methode DELETE fordert, dass die durch die Anfrage-URI identifizierte Ressource gelöscht wird. Bei Erfolg oder falls die Ressource vor der Anfrage nicht existierte, sollte ein Response Code 2.02 (Deleted) verwendet werden (SHOULD).

DELETE ist nicht safe, aber idempotent.

5.9. Definitionen der Antwortcodes

Jeder Response Code wird im Folgenden beschrieben, einschließlich aller in der Antwort erforderlichen Optionen. Wo angemessen, werden einige der Codes in Bezug auf verwandte Response Codes in HTTP [RFC2616] spezifiziert; dies bedeutet nicht, dass eine solche Beziehung die in Abschnitt 10 spezifizierte HTTP-Abbildung ändert.

5.9.1. Success 2.xx

Diese Klasse von Response Codes zeigt an, dass die Anfrage des Clients erfolgreich empfangen, verstanden und akzeptiert wurde.

5.9.1.1. 2.01 Created

Wie HTTP 201 "Created", aber nur als Antwort auf POST- und PUT-Anfragen verwendet. Die mit der Antwort zurückgegebene Nutzlast, falls vorhanden, ist eine Repräsentation des Aktionsergebnisses.

Wenn die Antwort eine oder mehrere Location-Path- und/oder Location-Query-Optionen enthält, geben die Werte dieser Optionen den Ort an, an dem die Ressource erstellt wurde. Andernfalls wurde die Ressource am Anfrage-URI erstellt. Ein Cache, der diese Antwort empfängt, muss jede gespeicherte Antwort für die erstellte Ressource als nicht frisch markieren (MUST).

Diese Antwort ist nicht cachefähig.

5.9.1.2. 2.02 Deleted

Dieser Response Code ist wie HTTP 204 "No Content", wird aber nur als Antwort auf Anfragen verwendet, die bewirken, dass die Ressource nicht mehr verfügbar ist, wie DELETE und unter bestimmten Umständen POST. Die mit der Antwort zurückgegebene Nutzlast, falls vorhanden, ist eine Repräsentation des Aktionsergebnisses.

Diese Antwort ist nicht cachefähig. Ein Cache muss jedoch jede gespeicherte Antwort für die gelöschte Ressource als nicht frisch markieren (MUST).

5.9.1.3. 2.03 Valid

Dieser Response Code ist verwandt mit HTTP 304 "Not Modified", wird aber nur verwendet, um anzuzeigen, dass die durch das in der enthaltenen ETag-Option angegebene Entity-Tag identifizierte Antwort gültig ist. Dementsprechend muss die Antwort eine ETag-Option enthalten (MUST) und darf keine Nutzlast enthalten (MUST NOT).

Wenn ein Cache, der die ETag-Antwortoption erkennt und verarbeitet, eine 2.03 (Valid)-Antwort empfängt, muss er die gespeicherte Antwort mit dem Wert der in der Antwort enthaltenen Max-Age-Option aktualisieren (MUST) (explizit oder implizit als Standardwert; siehe auch Abschnitt 5.6.2). Für jeden Typ von Safe-to-Forward-Option, der in der Antwort vorhanden ist, muss die (möglicherweise leere) Menge von Optionen dieses Typs, die in der gespeicherten Antwort vorhanden ist, durch die Menge von Optionen dieses Typs in der empfangenen Antwort ersetzt werden (MUST). (Unsafe-Optionen können eine ähnliche optionsspezifische Verarbeitung auslösen, wie sie von der Option definiert wird.)

5.9.1.4. 2.04 Changed

Dieser Response Code ist wie HTTP 204 "No Content", wird aber nur als Antwort auf POST- und PUT-Anfragen verwendet. Die mit der Antwort zurückgegebene Nutzlast, falls vorhanden, ist eine Repräsentation des Aktionsergebnisses.

Diese Antwort ist nicht cachefähig. Ein Cache muss jedoch jede gespeicherte Antwort für die geänderte Ressource als nicht frisch markieren (MUST).

5.9.1.5. 2.05 Content

Dieser Response Code ist wie HTTP 200 "OK", wird aber nur als Antwort auf GET-Anfragen verwendet.

Die mit der Antwort zurückgegebene Nutzlast ist eine Repräsentation der Zielressource.

Diese Antwort ist cachefähig: Caches können die Max-Age-Option verwenden, um die Freshness zu bestimmen (siehe Abschnitt 5.6.1), und (falls vorhanden) die ETag-Option zur Validierung (siehe Abschnitt 5.6.2).

5.9.2. Client Error 4.xx

Diese Klasse von Response Codes ist für Fälle gedacht, in denen der Client geirrt zu haben scheint. Diese Response Codes sind auf jede Anfragemethode anwendbar.

Der Server sollte unter den in Abschnitt 5.5.2 dargelegten Bedingungen eine Diagnosenutzlast aufnehmen (SHOULD).

Antworten dieser Klasse sind cachefähig: Caches können die Max-Age-Option verwenden, um die Freshness zu bestimmen (siehe Abschnitt 5.6.1). Sie können nicht validiert werden.

5.9.2.1. 4.00 Bad Request

Dieser Response Code ist wie HTTP 400 "Bad Request".

5.9.2.2. 4.01 Unauthorized

Der Client ist nicht berechtigt, die angeforderte Aktion auszuführen. Der Client sollte die Anfrage nicht wiederholen, ohne zuvor seinen Authentifizierungsstatus gegenüber dem Server zu verbessern (SHOULD NOT). Welcher spezifische Mechanismus hierfür verwendet werden kann, liegt außerhalb des Rahmens dieses Dokuments; siehe auch Abschnitt 9.

5.9.2.3. 4.02 Bad Option

Die Anfrage konnte vom Server aufgrund einer oder mehrerer nicht erkannter oder fehlerhafter Optionen nicht verstanden werden. Der Client sollte die Anfrage nicht ohne Änderung wiederholen (SHOULD NOT).

5.9.2.4. 4.03 Forbidden

Dieser Response Code ist wie HTTP 403 "Forbidden".

5.9.2.5. 4.04 Not Found

Dieser Response Code ist wie HTTP 404 "Not Found".

5.9.2.6. 4.05 Method Not Allowed

Dieser Response Code ist wie HTTP 405 "Method Not Allowed", aber ohne Entsprechung zum Header-Feld "Allow".

5.9.2.7. 4.06 Not Acceptable

Dieser Response Code ist wie HTTP 406 "Not Acceptable", aber ohne Response-Entity.

5.9.2.8. 4.12 Precondition Failed

Dieser Response Code ist wie HTTP 412 "Precondition Failed".

5.9.2.9. 4.13 Request Entity Too Large

Dieser Response Code ist wie HTTP 413 "Request Entity Too Large".

Die Antwort sollte eine Size1-Option (Abschnitt 5.10.9) enthalten, um die maximale Größe der Anfrage-Entity anzugeben, die der Server handhaben kann und zu handhaben bereit ist (SHOULD), es sei denn, der Server ist nicht in der Lage, diese Informationen bereitzustellen.

5.9.2.10. 4.15 Unsupported Content-Format

Dieser Response Code ist wie HTTP 415 "Unsupported Media Type".

5.9.3. Server Error 5.xx

Diese Klasse von Response Codes zeigt Fälle an, in denen der Server sich bewusst ist, geirrt zu haben oder die Anfrage nicht ausführen zu können. Diese Response Codes sind auf jede Anfragemethode anwendbar.

Der Server sollte unter den in Abschnitt 5.5.2 dargelegten Bedingungen eine Diagnosenutzlast aufnehmen (SHOULD).

Antworten dieser Klasse sind cachefähig: Caches können die Max-Age-Option verwenden, um die Freshness zu bestimmen (siehe Abschnitt 5.6.1). Sie können nicht validiert werden.

5.9.3.1. 5.00 Internal Server Error

Dieser Response Code ist wie HTTP 500 "Internal Server Error".

5.9.3.2. 5.01 Not Implemented

Dieser Response Code ist wie HTTP 501 "Not Implemented".

5.9.3.3. 5.02 Bad Gateway

Dieser Response Code ist wie HTTP 502 "Bad Gateway".

5.9.3.4. 5.03 Service Unavailable

Dieser Response Code ist wie HTTP 503 "Service Unavailable", verwendet aber die Max-Age-Option anstelle des Header-Felds "Retry-After", um die Anzahl der Sekunden anzugeben, nach denen erneut versucht werden soll.

5.9.3.5. 5.04 Gateway Timeout

Dieser Response Code ist wie HTTP 504 "Gateway Timeout".

5.9.3.6. 5.05 Proxying Not Supported

Der Server ist nicht in der Lage oder nicht bereit, als forward-proxy für die in der Proxy-Uri-Option angegebene URI oder unter Verwendung von Proxy-Scheme zu fungieren (siehe Abschnitt 5.10.2).

5.10. Optionsdefinitionen

Die einzelnen CoAP-Optionen sind in Tabelle 4 zusammengefasst und in den Unterabschnitten dieses Abschnitts erläutert.

In dieser Tabelle geben die Spalten C, U und N die Eigenschaften Critical, UnSafe bzw. NoCacheKey an. Da NoCacheKey nur für Optionen eine Bedeutung hat, die Safe-to-Forward sind (nicht als Unsafe gekennzeichnet), ist die Spalte für UnSafe-Optionen mit einem Bindestrich gefüllt.

No.	C	U	N	R	Name	Format	Length	Default
1	x			x	If-Match	opaque	0-8	(none)
3	x	x	-		Uri-Host	string	1-255	(see
								below)
4				x	ETag	opaque	1-8	(none)
5	x				If-None-Match	empty	0	(none)
7	x	x	-		Uri-Port	uint	0-2	(see
								below)
8				x	Location-Path	string	0-255	(none)
11	x	x	-	x	Uri-Path	string	0-255	(none)
12					Content-Format	uint	0-2	(none)
14		x	-		Max-Age	uint	0-4	60
15	x	x	-	x	Uri-Query	string	0-255	(none)
17	x				Accept	uint	0-2	(none)
20				x	Location-Query	string	0-255	(none)
35	x	x	-		Proxy-Uri	string	1-1034	(none)
39	x	x	-		Proxy-Scheme	string	1-255	(none)
60			x		Size1	uint	0-4	(none)

C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable

Tabelle 4: Optionen

5.10.1. Uri-Host, Uri-Port, Uri-Path und Uri-Query

Die Optionen Uri-Host, Uri-Port, Uri-Path und Uri-Query werden verwendet, um die Zielressource einer Anfrage an einen CoAP-Origin-Server anzugeben. Die Optionen kodieren die verschiedenen Komponenten der Anfrage-URI so, dass in den Optionswerten keine Prozentkodierung sichtbar ist und die vollständige URI an jedem beteiligten Endpunkt rekonstruiert werden kann. Die Syntax von CoAP-URIs ist in Abschnitt 6 definiert.

Die Schritte zum Zerlegen von URIs in Optionen sind in Abschnitt 6.4 definiert. Diese Schritte führen dazu, dass null oder mehr Uri-Host-, Uri-Port-, Uri-Path- und Uri-Query-Optionen in eine Anfrage aufgenommen werden, wobei jede Option die folgenden Werte hält:

• die Uri-Host-Option gibt den Internet-Host der angeforderten Ressource an,

• die Uri-Port-Option gibt die Portnummer der Transportschicht der Ressource an,

• jede Uri-Path-Option gibt ein Segment des absoluten Pfads zur Ressource an, und

• jede Uri-Query-Option gibt ein Argument an, das die Ressource parametrisiert.

Hinweis: Fragmente ([RFC3986], Abschnitt 3.5) sind nicht Teil der Anfrage-URI und werden daher nicht in einer CoAP-Anfrage übertragen.

Der Standardwert der Uri-Host-Option ist das IP-Literal, das die Ziel-IP-Adresse der Anfragenachricht darstellt. Ebenso ist der Standardwert der Uri-Port-Option der Ziel-UDP-Port. Die Standardwerte für die Optionen Uri-Host und Uri-Port sind für Anfragen an die meisten Server ausreichend. Ausdrückliche Uri-Host- und Uri-Port-Optionen werden typischerweise verwendet, wenn ein Endpunkt mehrere virtuelle Server beherbergt.

Die Optionen Uri-Path und Uri-Query können jede Zeichenfolge enthalten. Es wird keine Prozentkodierung durchgeführt. Der Wert einer Uri-Path-Option darf nicht "." oder ".." sein (MUST NOT) (da die Anfrage-URI aufgelöst werden muss, bevor sie in Optionen zerlegt wird).

Die Schritte zum Aufbau der Anfrage-URI aus den Optionen sind in Abschnitt 6.5 definiert. Beachten Sie, dass eine Implementierung nicht unbedingt die URI aufbauen muss; sie kann die Zielressource einfach durch Untersuchen der einzelnen Optionen nachschlagen.

Beispiele finden sich in Anhang B.

5.10.2. Proxy-Uri und Proxy-Scheme

Die Proxy-Uri-Option wird verwendet, um eine Anfrage an einen forward-proxy zu stellen (siehe Abschnitt 5.7). Der forward-proxy wird aufgefordert, die Anfrage weiterzuleiten oder sie aus einem gültigen Cache zu bedienen und die Antwort zurückzugeben.

Der Optionswert ist eine absolute-URI ([RFC3986], Abschnitt 4.3).

Beachten Sie, dass der forward-proxy die Anfrage an einen anderen Proxy oder direkt an den durch die absolute-URI angegebenen Server weiterleiten kann (MAY). Um Anfrageschleifen zu vermeiden, muss ein Proxy in der Lage sein, alle seine Servernamen zu erkennen, einschließlich aller Aliase, lokalen Varianten und der numerischen IP-Adressen (MUST).

Ein Endpunkt, der eine Anfrage mit einer Proxy-Uri-Option empfängt und nicht in der Lage oder nicht bereit ist, als forward-proxy für die Anfrage zu fungieren, muss die Rückgabe einer 5.05 (Proxying Not Supported)-Antwort bewirken (MUST).

Die Proxy-Uri-Option muss Vorrang vor allen Optionen Uri-Host, Uri-Port, Uri-Path oder Uri-Query haben (MUST) (von denen jede nicht in eine Anfrage aufgenommen werden darf, die die Proxy-Uri-Option enthält (MUST NOT)).

Als Sonderfall zur Vereinfachung vieler Proxy-Clients kann die absolute-URI aus den Uri--Optionen aufgebaut werden. Wenn eine Proxy-Scheme-Option vorhanden ist, wird die absolute-URI wie folgt aufgebaut: Aus den Uri--Optionen wird eine CoAP-URI aufgebaut, wie in Abschnitt 6.5 definiert. In der resultierenden URI wird dann das anfängliche Schema bis, aber ohne den folgenden Doppelpunkt durch den Inhalt der Proxy-Scheme-Option ersetzt. Beachten Sie, dass dieser Fall nur anwendbar ist, wenn die Komponenten der gewünschten URI außer der Schema-Komponente tatsächlich mit Uri-*-Optionen ausgedrückt werden können; um beispielsweise eine URI mit einer userinfo-Komponente in der Authority darzustellen, kann nur Proxy-Uri verwendet werden.

5.10.3. Content-Format

Die Content-Format-Option gibt das Repräsentationsformat der Nachrichtennutzlast an. Das Repräsentationsformat wird als numerischer Content-Format-Identifikator angegeben, der im Register "CoAP Content-Formats" definiert ist (Abschnitt 12.3). In Abwesenheit der Option wird kein Standardwert angenommen, d. h., das Repräsentationsformat jeder Repräsentationsnachrichtennutzlast ist unbestimmt (Abschnitt 5.5).

5.10.4. Accept

Die CoAP-Accept-Option kann verwendet werden, um anzugeben, welches Content-Format für den Client akzeptabel ist. Das Repräsentationsformat wird als numerischer Content-Format-Identifikator angegeben, der im Register "CoAP Content-Formats" definiert ist (Abschnitt 12.3). Wenn keine Accept-Option angegeben ist, drückt der Client keine Präferenz aus (es wird also kein Standardwert angenommen). Der Client bevorzugt, dass die vom Server zurückgegebene Repräsentation im angegebenen Content-Format ist. Der Server gibt das bevorzugte Content-Format zurück, wenn es verfügbar ist. Wenn das bevorzugte Content-Format nicht zurückgegeben werden kann, muss eine 4.06 "Not Acceptable" als Antwort gesendet werden (MUST), es sei denn, ein anderer Fehlercode hat für diese Antwort Vorrang.

5.10.5. Max-Age

Die Max-Age-Option gibt die maximale Zeit an, die eine Antwort zwischengespeichert werden darf, bevor sie als nicht frisch betrachtet wird (siehe Abschnitt 5.6.1).

Der Optionswert ist eine ganze Zahl von Sekunden zwischen 0 und 2**32-1 einschließlich (etwa 136,1 Jahre). In Abwesenheit der Option in einer Antwort wird ein Standardwert von 60 Sekunden angenommen.

Der Wert soll zum Zeitpunkt der Übertragung aktuell sein. Server, die Ressourcen mit strengen Toleranzen für den Wert von Max-Age bereitstellen, sollten den Wert vor jeder erneuten Übertragung aktualisieren (SHOULD). (Siehe auch Abschnitt 5.7.1.)

5.10.6. ETag

Ein Entity-Tag ist für die Verwendung als ressourcenlokaler Identifikator gedacht, um zwischen Repräsentationen derselben Ressource zu unterscheiden, die sich im Laufe der Zeit ändern. Es wird vom Server erzeugt, der die Ressource bereitstellt, und kann auf beliebig viele Arten erzeugt werden, darunter eine Version, Prüfsumme, Hash oder Zeit. Ein Endpunkt, der ein Entity-Tag empfängt, muss es als opak behandeln und keine Annahmen über dessen Inhalt oder Struktur treffen (MUST). (Endpunkte, die ein Entity-Tag erzeugen, werden ermutigt, die kompakteste mögliche Darstellung zu verwenden, insbesondere in Bezug auf Clients und Zwischeninstanzen, die möglicherweise mehrere ETag-Werte speichern möchten.)

5.10.6.1. ETag als Antwortoption

Die ETag-Option in einer Antwort liefert den aktuellen Wert (d. h. nach der Verarbeitung der Anfrage) des Entity-Tags für die "tagged representation". Wenn keine Location--Optionen vorhanden sind, ist die tagged representation die selected representation (Abschnitt 5.5.3) der Zielressource. Wenn eine oder mehrere Location--Optionen vorhanden sind und somit eine Location-URI angegeben wird (Abschnitt 5.10.7), ist die tagged representation die Repräsentation, die durch eine GET-Anfrage an die Location-URI abgerufen würde.

Eine ETag-Antwortoption kann bei jeder Antwort mitgeführt werden, für die es eine tagged representation gibt (z. B. wäre sie in einer 4.04- oder 4.00-Antwort nicht sinnvoll). Die ETag-Option darf in einer Antwort nicht mehr als einmal vorkommen (MUST NOT).

Es gibt keinen Standardwert für die ETag-Option; wenn sie in einer Antwort nicht vorhanden ist, macht der Server keine Aussage über das Entity-Tag für die tagged representation.

5.10.6.2. ETag als Anfrageoption

In einer GET-Anfrage kann ein Endpunkt, der eine oder mehrere zuvor von der Ressource erhaltene Repräsentationen hat und dazu ETag-Antwortoptionen erhalten hat, eine Instanz der ETag-Option für eine oder mehrere dieser gespeicherten Antworten angeben.

Ein Server kann eine 2.03 Valid-Antwort (Abschnitt 5.9.1.3) anstelle einer 2.05 Content-Antwort ausgeben, wenn eines der angegebenen ETags das Entity-Tag für die aktuelle Repräsentation ist, d. h. gültig ist; die 2.03 Valid-Antwort gibt dann dieses spezifische ETag in einer Antwortoption wieder.

Effektiv kann ein Client feststellen, ob eine der gespeicherten Repräsentationen aktuell ist (siehe Abschnitt 5.6.2), ohne sie erneut übertragen zu müssen.

Die ETag-Option kann null, einmal oder mehrfach in einer Anfrage vorkommen (MAY).

5.10.7. Location-Path und Location-Query

Die Optionen Location-Path und Location-Query geben zusammen eine relative URI an, die entweder aus einem absoluten Pfad, einer Query-Zeichenkette oder beidem besteht. Eine Kombination dieser Optionen wird in eine 2.01 (Created)-Antwort aufgenommen, um den Ort der als Ergebnis einer POST-Anfrage erstellten Ressource anzugeben (siehe Abschnitt 5.8.2). Der Ort wird relativ zur Anfrage-URI aufgelöst.

Wenn eine Antwort mit einer oder mehreren Location-Path- und/oder Location-Query-Optionen einen Cache durchläuft, der diese Optionen interpretiert, und die implizierte URI eine oder mehrere derzeit gespeicherte Antworten identifiziert, müssen diese Einträge als nicht frisch markiert werden (MUST).

Jede Location-Path-Option gibt ein Segment des absoluten Pfads zur Ressource an, und jede Location-Query-Option gibt ein Argument an, das die Ressource parametrisiert. Die Optionen Location-Path und Location-Query können jede Zeichenfolge enthalten. Es wird keine Prozentkodierung durchgeführt. Der Wert einer Location-Path-Option darf nicht "." oder ".." sein (MUST NOT).

Die Schritte zum Aufbau der Location-URI aus den Optionen sind analog zu Abschnitt 6.5, mit der Ausnahme, dass die ersten fünf Schritte übersprungen werden und das Ergebnis eine relative URI-Referenz ist, die dann relativ zur Anfrage-URI interpretiert wird. Beachten Sie, dass die auf diese Weise aufgebaute relative URI-Referenz immer einen absoluten Pfad enthält (z. B. bedeutet das Weglassen von Location-Path, aber das Angeben von Location-Query, dass die Pfadkomponente in der URI "/" ist).

Die Optionen, die zur Berechnung der relativen URI-Referenz verwendet werden, werden zusammenfassend Location--Optionen genannt. Über Location-Path und Location-Query hinaus können in Zukunft weitere Location--Optionen definiert werden, und es wurden die Optionsnummern 128, 132, 136 und 140 reserviert. Wenn eine dieser reservierten Optionsnummern zusätzlich zu Location-Path und/oder Location-Query auftritt und nicht unterstützt wird, muss ein 4.02 (Bad Option)-Fehler zurückgegeben werden (MUST).

5.10.8. Conditional Request Options

Bedingte Anfrageoptionen ermöglichen es einem Client, den Server zu bitten, die Anfrage nur dann auszuführen, wenn bestimmte, durch die Option angegebene Bedingungen erfüllt sind.

Für jede dieser Optionen gilt: Wenn die angegebene Bedingung nicht erfüllt ist, darf der Server die angeforderte Methode nicht ausführen (MUST NOT). Stattdessen muss der Server mit dem Response Code 4.12 (Precondition Failed) antworten (MUST).

Wenn die Bedingung erfüllt ist, führt der Server die Anfragemethode aus, als wären die bedingten Anfrageoptionen nicht vorhanden.

Wenn die Anfrage ohne die bedingten Anfrageoptionen zu etwas anderem als einem Response Code 2.xx oder 4.12 führen würde, können alle bedingten Anfrageoptionen ignoriert werden (MAY).

5.10.8.1. If-Match

Die If-Match-Option kann verwendet werden, um eine Anfrage vom aktuellen Vorhandensein oder Wert eines ETag für eine oder mehrere Repräsentationen der Zielressource abhängig zu machen (MAY). If-Match ist im Allgemeinen nützlich für Ressourcenaktualisierungsanfragen wie PUT-Anfragen als Mittel zum Schutz vor versehentlichem Überschreiben, wenn mehrere Clients parallel auf dieselbe Ressource einwirken (d. h. das Problem des "lost update").

Der Wert einer If-Match-Option ist entweder ein ETag oder die leere Zeichenkette. Eine If-Match-Option mit einem ETag passt zu einer Repräsentation mit genau diesem ETag. Eine If-Match-Option mit einem leeren Wert passt zu jeder vorhandenen Repräsentation (d. h., sie stellt die Vorbedingung auf die Existenz irgendeiner aktuellen Repräsentation für die Zielressource).

Die If-Match-Option kann mehrfach vorkommen. Wenn eine der Optionen passt, ist die Bedingung erfüllt.

Wenn es eine oder mehrere If-Match-Optionen gibt, aber keine der Optionen passt, ist die Bedingung nicht erfüllt.

5.10.8.2. If-None-Match

Die If-None-Match-Option kann verwendet werden, um eine Anfrage vom Nichtvorhandensein der Zielressource abhängig zu machen (MAY). If-None-Match ist nützlich für Ressourcenerstellungsanfragen wie PUT-Anfragen als Mittel zum Schutz vor versehentlichem Überschreiben, wenn mehrere Clients parallel auf dieselbe Ressource einwirken. Die If-None-Match-Option trägt keinen Wert.

Wenn die Zielressource existiert, ist die Bedingung nicht erfüllt.

(Es ist nicht sehr nützlich, die Optionen If-Match und If-None-Match in einer Anfrage zu kombinieren, da die Bedingung dann niemals erfüllt sein wird.)

5.10.9. Size1-Option

Die Size1-Option liefert Größeninformationen über die Ressourcenrepräsentation in einer Anfrage. Der Optionswert ist eine ganze Zahl von Bytes. Ihre Hauptverwendung liegt bei blockweisen Übertragungen [BLOCK]. In der vorliegenden Spezifikation wird sie in 4.13-Antworten (Abschnitt 5.9.2.9) verwendet, um die maximale Größe der Anfrage-Entity anzugeben, die der Server handhaben kann und zu handhaben bereit ist.