6. CoAP URIs

CoAP utilise les schémas URI "coap" et "coaps" pour identifier les ressources CoAP et fournir un moyen de localiser la ressource. Les ressources sont organisées hiérarchiquement et régies par un serveur d'origine CoAP potentiel écoutant les requêtes CoAP ("coap") ou les requêtes CoAP sécurisées par DTLS ("coaps") sur un port UDP donné. Le serveur CoAP est identifié par le composant d'autorité de la syntaxe générique, qui comprend un composant hôte et un numéro de port UDP facultatif. Le reste de l'URI identifie une ressource qui peut être opérée par les méthodes définies par le protocole CoAP. Les schémas URI "coap" et "coaps" peuvent ainsi être comparés aux schémas URI "http" et "https", respectivement.

La syntaxe des schémas URI "coap" et "coaps" est spécifiée dans cette section en forme de Backus-Naur augmentée (ABNF) [RFC5234]. Les définitions de "host", "port", "path-abempty", "query", "segment", "IP-literal", "IPv4address" et "reg-name" sont adoptées de [RFC3986].

Note d'implémentation: Malheureusement, au fil du temps, le formatage des URI est devenu assez compliqué. Les implémenteurs sont encouragés à lire attentivement [RFC3986]. Par exemple, l'ABNF pour les adresses IPv6 est plus complexe qu'on pourrait s'y attendre. De plus, les implémenteurs doivent veiller à effectuer exactement une passe de décodage de pourcentage ou d'encodage de pourcentage dans le processus d'un URI vers ses composants décodés ou vice versa. L'encodage en pourcentage est primordial pour la transparence des données mais peut conduire à des résultats inhabituels, tels qu'un caractère barre oblique dans un composant de chemin.

6.1. coap URI Scheme (Schéma URI coap)

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

Si le composant hôte est fourni comme IP-literal ou IPv4address, alors le serveur CoAP peut être atteint à cette adresse IP. Si l'hôte est un nom enregistré, alors ce nom est considéré comme un identifiant indirect et le point de terminaison peut utiliser un service de résolution de noms, tel que DNS, pour trouver une adresse pour cet hôte. L'hôte NE DOIT PAS être vide; si un URI est reçu avec une autorité absente ou un hôte vide, alors il DOIT être considéré comme invalide. Le sous-composant port indique le port UDP sur lequel se trouve le serveur CoAP. S'il est vide ou non donné, alors le port par défaut 5683 est supposé.

Le chemin identifie une ressource dans la portée de l'hôte et du port. Il se compose d'une séquence de segments de chemin séparés par des caractères barre oblique (U+002F SOLIDUS "/").

La requête sert à paramétrer davantage la ressource. Elle se compose d'une séquence de paramètres séparés par des caractères esperluette (U+0026 AMPERSAND "&"). Les paramètres sont généralement sous la forme de paires "clé=valeur".

Le schéma URI "coap" prend en charge le préfixe de chemin "/.well-known/" défini par [RFC5785] pour les "emplacements bien connus" dans l'espace de noms d'un hôte. Cela permet la découverte de politiques ou d'autres informations sur un hôte ("métadonnées à l'échelle du site"), telles que les ressources hébergées (voir Section 7).

Les concepteurs d'applications sont encouragés à utiliser des URI courts mais descriptifs. Comme les environnements dans lesquels CoAP est utilisé sont généralement contraints en termes de bande passante et d'énergie, le compromis entre ces deux qualités devrait pencher vers la concision sans ignorer le caractère descriptif.

6.2. coaps URI Scheme (Schéma URI coaps)

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

Toutes les exigences énumérées ci-dessus pour le schéma "coap" sont également des exigences pour le schéma "coaps", sauf qu'un port UDP par défaut de 5684 est supposé si le sous-composant port est vide ou non donné, et les datagrammes UDP DOIVENT être sécurisés par l'utilisation de DTLS comme décrit dans la Section 9.1.

Les considérations de mise en cache pour les réponses aux requêtes identifiées "coaps" sont discutées dans la Section 11.2.

Les ressources rendues disponibles via le schéma "coaps" n'ont pas d'identité partagée avec le schéma "coap" même si leurs identifiants de ressource indiquent la même autorité (le même hôte écoutant le même port UDP). Ce sont des espaces de noms distincts et sont considérés comme des serveurs d'origine distincts.

6.3. Normalization and Comparison Rules (Règles de Normalisation et de Comparaison)

Étant donné que les schémas URI "coap" et "coaps" sont conformes à la syntaxe générique URI, de tels URI sont normalisés et comparés selon l'algorithme défini dans [RFC3986], Section 6, en utilisant les valeurs par défaut décrites ci-dessus pour chaque schéma.

Si le port est égal au port par défaut pour un schéma, la forme normale est d'omettre le sous-composant port. De même, un composant de chemin vide est équivalent à un chemin absolu de "/", donc la forme normale est de fournir un chemin de "/". Le schéma et l'hôte ne sont pas sensibles à la casse et sont normalement fournis en minuscules; les IP-literals sont sous forme recommandée [RFC5952]; tous les autres composants sont comparés de manière sensible à la casse. Les caractères autres que ceux dans l'ensemble "reserved" sont équivalents à leurs octets encodés en pourcentage (voir [RFC3986], Section 2.1): la forme normale est de ne pas les encoder.

Par exemple, les trois URI suivants sont équivalents et provoquent l'apparition des mêmes options et valeurs d'option dans les messages CoAP:

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 (Décomposition des URI en Options)

Les étapes pour analyser les options d'une requête à partir d'une chaîne |url| sont les suivantes. Ces étapes aboutissent soit à l'inclusion de zéro ou plusieurs options Uri-Host, Uri-Port, Uri-Path et Uri-Query dans la requête, soit elles échouent.

1. Si la chaîne |url| n'est pas un URI absolu ([RFC3986]), alors échouer cet algorithme.

2. Résoudre la chaîne |url| en utilisant le processus de résolution de référence défini par [RFC3986]. À ce stade, l'URL est en encodage ASCII [RFC0020], même si les composants décodés seront interprétés en UTF-8 [RFC3629] après les étapes 5, 8 et 9.

   Note: Peu importe par rapport à quoi il est résolu à ce stade, puisque nous savons déjà que c'est une URL absolue.

3. Si |url| n'a pas de composant <scheme> dont la valeur, après conversion en minuscules ASCII, est "coap" ou "coaps", alors échouer cet algorithme.

4. Si |url| a un composant <fragment>, alors échouer cet algorithme.

5. Si le composant <host> de |url| ne représente pas l'adresse IP de destination de la requête en tant qu'IP-literal ou IPv4address, inclure une option Uri-Host et laisser la valeur de cette option être la valeur du composant <host> de |url|, convertie en minuscules ASCII, puis convertir tous les encodages en pourcentage ("%" suivi de deux chiffres hexadécimaux) en caractères correspondants.

   Note: Dans le cas habituel où l'adresse IP de destination de la requête est dérivée de la partie hôte, cela garantit que l'option Uri-Host est élective pour la forme reg-name du composant <host>.

6. Si |url| a un composant <port>, alors laisser |port| être la valeur de ce composant interprétée comme un entier décimal; sinon, laisser |port| être le port par défaut pour le schéma.

7. Si |port| n'est pas égal au port UDP de destination de la requête, inclure une option Uri-Port et laisser la valeur de cette option être |port|.

8. Si la valeur du composant <path> de |url| est vide ou consiste en un seul caractère barre oblique (U+002F SOLIDUS "/"), alors passer à l'étape suivante.

   Sinon, pour chaque segment dans le composant <path>, inclure une option Uri-Path et laisser la valeur de cette option être le segment (sans les caractères barre oblique de séparation) après conversion de chaque encodage en pourcentage ("%" suivi de deux chiffres hexadécimaux) en l'octet correspondant.

9. Si |url| a un composant <query>, alors, pour chaque paramètre dans le composant <query>, inclure une option Uri-Query et laisser la valeur de cette option être le paramètre (sans le point d'interrogation et les caractères esperluette de séparation) après conversion de chaque encodage en pourcentage en l'octet correspondant.

Notez que ces règles résolvent complètement tout encodage en pourcentage.

6.5. Composing URIs from Options (Composition d'URI à partir d'Options)

Les étapes pour construire un URI à partir des options d'une requête sont les suivantes. Ces étapes aboutissent soit à un URI, soit elles échouent. Dans ces étapes, encoder en pourcentage un caractère signifie remplacer chacun de ses octets (encodés en UTF-8) par un caractère "%" suivi de deux chiffres hexadécimaux représentant l'octet, où les chiffres A-F sont en majuscules (comme défini dans [RFC3986], Section 2.1; pour réduire la variabilité, la notation hexadécimale dans les encodages en pourcentage dans les URI CoAP DOIT utiliser des lettres majuscules). Les définitions de "unreserved" et "sub-delims" sont adoptées de [RFC3986].

1. Si la requête est sécurisée à l'aide de DTLS, laisser |url| être la chaîne "coaps://". Sinon, laisser |url| être la chaîne "coap://".

2. Si la requête inclut une option Uri-Host, laisser |host| être la valeur de cette option, où tous les caractères non-ASCII sont remplacés par leur encodage en pourcentage correspondant. Si |host| n'est pas un reg-name valide ou IP-literal ou IPv4address, échouer l'algorithme. Si la requête n'inclut pas d'option Uri-Host, laisser |host| être l'IP-literal (en utilisant les conventions de [RFC5952]) ou IPv4address représentant l'adresse IP de destination de la requête.

3. Ajouter |host| à |url|.

4. Si la requête inclut une option Uri-Port, laisser |port| être la valeur de cette option. Sinon, laisser |port| être le port UDP de destination de la requête.

5. Si |port| n'est pas le port par défaut pour le schéma, ajouter un seul caractère U+003A COLON (":") suivi de la représentation décimale de |port| à |url|.

6. Laisser |resource name| être la chaîne vide. Pour chaque option Uri-Path dans la requête, ajouter un seul caractère U+002F SOLIDUS ("/") suivi de la valeur de l'option à |resource name|, après conversion de tout caractère qui n'est pas dans l'ensemble "unreserved", ou n'est pas dans l'ensemble "sub-delims", ou n'est pas un caractère U+003A COLON (":"), ou n'est pas un caractère U+0040 COMMERCIAL AT ("@"), en sa forme encodée en pourcentage.

7. Si |resource name| est la chaîne vide, le définir à un seul caractère U+002F SOLIDUS ("/").

8. Pour chaque option Uri-Query dans la requête, ajouter un seul caractère U+003F QUESTION MARK ("?") (pour la première option) ou U+0026 AMPERSAND ("&") (pour les options suivantes) suivi de la valeur de l'option à |resource name|, après conversion de tout caractère qui n'est pas dans l'ensemble "unreserved", ou n'est pas dans l'ensemble "sub-delims" (sauf U+0026 AMPERSAND ("&")), ou n'est pas un U+003A COLON (":"), ou n'est pas un U+0040 COMMERCIAL AT ("@"), ou n'est pas un U+002F SOLIDUS ("/"), ou n'est pas un caractère U+003F QUESTION MARK ("?"), en sa forme encodée en pourcentage.

9. Ajouter |resource name| à |url|.

10. Retourner |url|.

Notez que ces étapes ont été conçues pour aboutir à un URI sous forme normale (voir Section 6.3).