6. CoAP URIs

CoAP verwendet die URI-Schemata "coap" und "coaps" zur Identifizierung von CoAP-Ressourcen und zur Bereitstellung einer Möglichkeit, die Ressource zu lokalisieren. Ressourcen sind hierarchisch organisiert und werden von einem potenziellen CoAP-Ursprungsserver verwaltet, der auf einem bestimmten UDP-Port auf CoAP-Anfragen ("coap") oder DTLS-gesicherte CoAP-Anfragen ("coaps") lauscht. Der CoAP-Server wird durch die Autoritätskomponente der generischen Syntax identifiziert, die eine Hostkomponente und eine optionale UDP-Portnummer umfasst. Der Rest des URI identifiziert eine Ressource, die durch die vom CoAP-Protokoll definierten Methoden betrieben werden kann. Die URI-Schemata "coap" und "coaps" können somit mit den URI-Schemata "http" und "https" verglichen werden.

Die Syntax der URI-Schemata "coap" und "coaps" wird in diesem Abschnitt in erweiterter Backus-Naur-Form (ABNF) [RFC5234] spezifiziert. Die Definitionen von "host", "port", "path-abempty", "query", "segment", "IP-literal", "IPv4address" und "reg-name" werden von [RFC3986] übernommen.

Implementierungshinweis: Leider ist die URI-Formatierung im Laufe der Zeit ziemlich kompliziert geworden. Implementierer werden ermutigt, [RFC3986] sorgfältig zu lesen. Zum Beispiel ist die ABNF für IPv6-Adressen komplexer als erwartet. Außerdem sollten Implementierer darauf achten, genau einen Prozent-Dekodierungs- oder Prozent-Kodierungsdurchgang im Prozess von einem URI zu seinen dekodierten Komponenten oder zurück durchzuführen. Prozentkodierung ist für die Datentransparenz von größter Bedeutung, kann jedoch zu ungewöhnlichen Ergebnissen führen, wie z.B. einem Schrägstrich-Zeichen in einer Pfadkomponente.

6.1. coap URI Scheme (coap-URI-Schema)

coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]

Wenn die Hostkomponente als IP-literal oder IPv4address bereitgestellt wird, kann der CoAP-Server unter dieser IP-Adresse erreicht werden. Wenn der Host ein registrierter Name ist, wird dieser Name als indirekter Identifikator betrachtet und der Endpunkt kann einen Namensauflösungsdienst wie DNS verwenden, um eine Adresse für diesen Host zu finden. Der Host DARF NICHT leer sein; wenn ein URI mit fehlender Autorität oder leerem Host empfangen wird, MUSS er als ungültig betrachtet werden. Die Portsubkomponente gibt den UDP-Port an, auf dem sich der CoAP-Server befindet. Wenn sie leer ist oder nicht angegeben wird, wird der Standardport 5683 angenommen.

Der Pfad identifiziert eine Ressource im Rahmen des Hosts und Ports. Er besteht aus einer Sequenz von Pfadsegmenten, die durch Schrägstrich-Zeichen (U+002F SOLIDUS "/") getrennt sind.

Die Abfrage dient dazu, die Ressource weiter zu parametrisieren. Sie besteht aus einer Sequenz von Parametern, die durch Und-Zeichen (U+0026 AMPERSAND "&") getrennt sind. Parameter haben typischerweise die Form von "Schlüssel=Wert"-Paaren.

Das URI-Schema "coap" unterstützt das Pfadpräfix "/.well-known/", das durch [RFC5785] für "bekannte Orte" im Namensraum eines Hosts definiert ist. Dies ermöglicht die Entdeckung von Richtlinien oder anderen Informationen über einen Host ("standortweite Metadaten"), wie z.B. gehostete Ressourcen (siehe Abschnitt 7).

Anwendungsdesigner werden ermutigt, kurze, aber beschreibende URIs zu verwenden. Da die Umgebungen, in denen CoAP verwendet wird, normalerweise in Bezug auf Bandbreite und Energie eingeschränkt sind, sollte der Kompromiss zwischen diesen beiden Qualitäten zur Kürze tendieren, ohne die Beschreibungsfähigkeit zu ignorieren.

6.2. coaps URI Scheme (coaps-URI-Schema)

coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty [ "?" query ]

Alle oben für das Schema "coap" aufgeführten Anforderungen gelten auch für das Schema "coaps", außer dass ein Standard-UDP-Port von 5684 angenommen wird, wenn die Portsubkomponente leer ist oder nicht angegeben wird, und die UDP-Datagramme MÜSSEN durch die Verwendung von DTLS wie in Abschnitt 9.1 beschrieben gesichert werden.

Überlegungen zum Caching von Antworten auf "coaps"-identifizierte Anfragen werden in Abschnitt 11.2 diskutiert.

Über das Schema "coaps" verfügbar gemachte Ressourcen haben keine gemeinsame Identität mit dem Schema "coap", selbst wenn ihre Ressourcenidentifikatoren dieselbe Autorität anzeigen (derselbe Host, der auf demselben UDP-Port lauscht). Sie sind unterschiedliche Namensräume und werden als unterschiedliche Ursprungsserver betrachtet.

6.3. Normalization and Comparison Rules (Normalisierungs- und Vergleichsregeln)

Da die URI-Schemata "coap" und "coaps" der generischen URI-Syntax entsprechen, werden solche URIs gemäß dem in [RFC3986], Abschnitt 6, definierten Algorithmus unter Verwendung der oben für jedes Schema beschriebenen Standardwerte normalisiert und verglichen.

Wenn der Port dem Standardport für ein Schema entspricht, besteht die Normalform darin, die Portsubkomponente wegzulassen. Ebenso ist eine leere Pfadkomponente äquivalent zu einem absoluten Pfad von "/", daher besteht die Normalform darin, einen Pfad von "/" bereitzustellen. Schema und Host sind nicht groß-/kleinschreibungssensitiv und werden normalerweise in Kleinbuchstaben bereitgestellt; IP-Literale sind in der empfohlenen Form [RFC5952]; alle anderen Komponenten werden groß-/kleinschreibungssensitiv verglichen. Zeichen außer denen im "reserved"-Set sind äquivalent zu ihren prozentkodierungs-Bytes (siehe [RFC3986], Abschnitt 2.1): die Normalform besteht darin, sie nicht zu kodieren.

Zum Beispiel sind die folgenden drei URIs äquivalent und führen dazu, dass dieselben Optionen und Optionswerte in den CoAP-Nachrichten erscheinen:

coap://example.com:5683/~sensors/temp.xml
coap://EXAMPLE.com/%7Esensors/temp.xml
coap://EXAMPLE.com:/%7esensors/temp.xml

6.4. Decomposing URIs into Options (URIs in Optionen zerlegen)

Die Schritte zum Parsen der Optionen einer Anfrage aus einer Zeichenfolge |url| sind wie folgt. Diese Schritte führen entweder dazu, dass null oder mehr Uri-Host-, Uri-Port-, Uri-Path- und Uri-Query-Optionen in die Anfrage aufgenommen werden, oder sie schlagen fehl.

1. Wenn die Zeichenfolge |url| kein absoluter URI ist ([RFC3986]), dann schlägt dieser Algorithmus fehl.

2. Lösen Sie die Zeichenfolge |url| unter Verwendung des von [RFC3986] definierten Prozesses der Referenzauflösung auf. In diesem Stadium ist die URL in ASCII-Kodierung [RFC0020], obwohl die dekodierten Komponenten nach den Schritten 5, 8 und 9 in UTF-8 [RFC3629] interpretiert werden.

   Hinweis: Es ist an diesem Punkt egal, relativ zu was es aufgelöst wird, da wir bereits wissen, dass es eine absolute URL ist.

3. Wenn |url| keine <scheme>-Komponente hat, deren Wert nach Konvertierung in ASCII-Kleinbuchstaben "coap" oder "coaps" ist, dann schlägt dieser Algorithmus fehl.

4. Wenn |url| eine <fragment>-Komponente hat, dann schlägt dieser Algorithmus fehl.

5. Wenn die <host>-Komponente von |url| nicht die Ziel-IP-Adresse der Anfrage als IP-literal oder IPv4address darstellt, schließen Sie eine Uri-Host-Option ein und lassen Sie den Wert dieser Option den Wert der <host>-Komponente von |url| sein, konvertiert in ASCII-Kleinbuchstaben, und konvertieren Sie dann alle Prozentkodierungen ("%" gefolgt von zwei Hexadezimalziffern) in die entsprechenden Zeichen.

   Hinweis: Im üblichen Fall, in dem die Ziel-IP-Adresse der Anfrage aus dem Hostteil abgeleitet wird, stellt dies sicher, dass die Uri-Host-Option für die reg-name-Form der <host>-Komponente wählbar ist.

6. Wenn |url| eine <port>-Komponente hat, dann sei |port| der Wert dieser Komponente, interpretiert als Dezimalzahl; andernfalls sei |port| der Standardport für das Schema.

7. Wenn |port| nicht dem Ziel-UDP-Port der Anfrage entspricht, schließen Sie eine Uri-Port-Option ein und lassen Sie den Wert dieser Option |port| sein.

8. Wenn der Wert der <path>-Komponente von |url| leer ist oder aus einem einzelnen Schrägstrich-Zeichen (U+002F SOLIDUS "/") besteht, dann gehen Sie zum nächsten Schritt über.

   Andernfalls schließen Sie für jedes Segment in der <path>-Komponente eine Uri-Path-Option ein und lassen Sie den Wert dieser Option das Segment sein (ohne die trennenden Schrägstrich-Zeichen), nachdem jede Prozentkodierung ("%" gefolgt von zwei Hexadezimalziffern) in das entsprechende Byte konvertiert wurde.

9. Wenn |url| eine <query>-Komponente hat, dann schließen Sie für jeden Parameter in der <query>-Komponente eine Uri-Query-Option ein und lassen Sie den Wert dieser Option den Parameter sein (ohne das Fragezeichen und die trennenden Und-Zeichen), nachdem jede Prozentkodierung in das entsprechende Byte konvertiert wurde.

Beachten Sie, dass diese Regeln jede Prozentkodierung vollständig auflösen.

6.5. Composing URIs from Options (URIs aus Optionen zusammensetzen)

Die Schritte zum Konstruieren eines URI aus den Optionen einer Anfrage sind wie folgt. Diese Schritte führen entweder zu einem URI oder sie schlagen fehl. In diesen Schritten bedeutet das Prozentkodieren eines Zeichens, jedes seiner (UTF-8-kodierten) Bytes durch ein "%"-Zeichen gefolgt von zwei Hexadezimalziffern, die das Byte darstellen, zu ersetzen, wobei die Ziffern A-F in Großbuchstaben sind (wie in [RFC3986], Abschnitt 2.1 definiert; um Variabilität zu reduzieren, MUSS die Hexadezimalnotation in Prozentkodierungen in CoAP-URIs Großbuchstaben verwenden). Die Definitionen von "unreserved" und "sub-delims" werden von [RFC3986] übernommen.

1. Wenn die Anfrage mit DTLS gesichert ist, sei |url| die Zeichenfolge "coaps://". Andernfalls sei |url| die Zeichenfolge "coap://".

2. Wenn die Anfrage eine Uri-Host-Option enthält, sei |host| der Wert dieser Option, wobei alle Nicht-ASCII-Zeichen durch ihre entsprechende Prozentkodierung ersetzt werden. Wenn |host| kein gültiger reg-name oder IP-literal oder IPv4address ist, schlägt der Algorithmus fehl. Wenn die Anfrage keine Uri-Host-Option enthält, sei |host| das IP-literal (unter Verwendung der Konventionen von [RFC5952]) oder IPv4address, das die Ziel-IP-Adresse der Anfrage darstellt.

3. Fügen Sie |host| zu |url| hinzu.

4. Wenn die Anfrage eine Uri-Port-Option enthält, sei |port| der Wert dieser Option. Andernfalls sei |port| der Ziel-UDP-Port der Anfrage.

5. Wenn |port| nicht der Standardport für das Schema ist, fügen Sie ein einzelnes Zeichen U+003A COLON (":") gefolgt von der Dezimaldarstellung von |port| zu |url| hinzu.

6. Sei |resource name| die leere Zeichenfolge. Fügen Sie für jede Uri-Path-Option in der Anfrage ein einzelnes Zeichen U+002F SOLIDUS ("/") gefolgt vom Wert der Option zu |resource name| hinzu, nachdem jedes Zeichen, das nicht im "unreserved"-Set ist, oder nicht im "sub-delims"-Set ist, oder kein U+003A COLON (":")-Zeichen ist, oder kein U+0040 COMMERCIAL AT ("@")-Zeichen ist, in seine prozentkodierte Form konvertiert wurde.

7. Wenn |resource name| die leere Zeichenfolge ist, setzen Sie sie auf ein einzelnes Zeichen U+002F SOLIDUS ("/").

8. Fügen Sie für jede Uri-Query-Option in der Anfrage ein einzelnes Zeichen U+003F QUESTION MARK ("?") (für die erste Option) oder U+0026 AMPERSAND ("&") (für nachfolgende Optionen) gefolgt vom Wert der Option zu |resource name| hinzu, nachdem jedes Zeichen, das nicht im "unreserved"-Set ist, oder nicht im "sub-delims"-Set ist (außer U+0026 AMPERSAND ("&")), oder kein U+003A COLON (":") ist, oder kein U+0040 COMMERCIAL AT ("@") ist, oder kein U+002F SOLIDUS ("/") ist, oder kein U+003F QUESTION MARK ("?")-Zeichen ist, in seine prozentkodierte Form konvertiert wurde.

9. Fügen Sie |resource name| zu |url| hinzu.

10. Geben Sie |url| zurück.

Beachten Sie, dass diese Schritte so konzipiert wurden, dass sie zu einem URI in Normalform führen (siehe Abschnitt 6.3).