6. CoAP URIs

CoAP utilizza gli schemi URI "coap" e "coaps" per identificare le risorse CoAP e fornire un mezzo per localizzare la risorsa. Le risorse sono organizzate gerarchicamente e governate da un potenziale server di origine CoAP in ascolto di richieste CoAP ("coap") o richieste CoAP protette da DTLS ("coaps") su una determinata porta UDP. Il server CoAP è identificato dal componente authority della sintassi generica, che include un componente host e un numero di porta UDP opzionale. Il resto dell'URI identifica una risorsa che può essere operata dai metodi definiti dal protocollo CoAP. Gli schemi URI "coap" e "coaps" possono quindi essere paragonati agli schemi URI "http" e "https", rispettivamente.

La sintassi degli schemi URI "coap" e "coaps" è specificata in questa sezione in Augmented Backus-Naur Form (ABNF) [RFC5234]. Le definizioni di "host", "port", "path-abempty", "query", "segment", "IP-literal", "IPv4address" e "reg-name" sono adottate da [RFC3986].

Nota di implementazione: Sfortunatamente, nel tempo, la formattazione degli URI è diventata piuttosto complicata. Si consiglia agli implementatori di leggere attentamente [RFC3986]. Ad esempio, l'ABNF per gli indirizzi IPv6 è più complesso di quanto ci si potrebbe aspettare. Inoltre, gli implementatori dovrebbero prestare attenzione a eseguire esattamente un passaggio di decodifica percentuale o codifica percentuale nel processo da un URI ai suoi componenti decodificati o viceversa. La codifica percentuale è fondamentale per la trasparenza dei dati ma può portare a risultati insoliti, come un carattere barra in un componente di percorso.

6.1. coap URI Scheme (Schema URI coap)

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

Se il componente host è fornito come IP-literal o IPv4address, allora il server CoAP può essere raggiunto a quell'indirizzo IP. Se l'host è un nome registrato, allora quel nome è considerato un identificatore indiretto e l'endpoint potrebbe utilizzare un servizio di risoluzione dei nomi, come DNS, per trovare un indirizzo per quell'host. L'host NON DEVE essere vuoto; se viene ricevuto un URI con un'autorità assente o un host vuoto, allora DEVE essere considerato non valido. Il sottocomponente port indica la porta UDP su cui si trova il server CoAP. Se è vuoto o non fornito, allora si presume la porta predefinita 5683.

Il percorso identifica una risorsa nell'ambito dell'host e della porta. È costituito da una sequenza di segmenti di percorso separati da caratteri barra (U+002F SOLIDUS "/").

La query serve a parametrizzare ulteriormente la risorsa. È costituita da una sequenza di parametri separati da caratteri e commerciale (U+0026 AMPERSAND "&"). I parametri sono tipicamente nella forma di coppie "chiave=valore".

Lo schema URI "coap" supporta il prefisso di percorso "/.well-known/" definito da [RFC5785] per "posizioni ben note" nello spazio dei nomi di un host. Questo consente la scoperta di politiche o altre informazioni su un host ("metadati a livello di sito"), come le risorse ospitate (vedere Sezione 7).

I progettisti di applicazioni sono incoraggiati a utilizzare URI brevi ma descrittivi. Poiché gli ambienti in cui viene utilizzato CoAP sono solitamente vincolati in termini di larghezza di banda ed energia, il compromesso tra queste due qualità dovrebbe propendere verso la concisione senza ignorare la descrittività.

6.2. coaps URI Scheme (Schema URI coaps)

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

Tutti i requisiti elencati sopra per lo schema "coap" sono anche requisiti per lo schema "coaps", tranne che si presume una porta UDP predefinita di 5684 se il sottocomponente port è vuoto o non fornito, e i datagrammi UDP DEVONO essere protetti attraverso l'uso di DTLS come descritto nella Sezione 9.1.

Le considerazioni sulla memorizzazione nella cache per le risposte alle richieste identificate "coaps" sono discusse nella Sezione 11.2.

Le risorse rese disponibili tramite lo schema "coaps" non hanno identità condivisa con lo schema "coap" anche se i loro identificatori di risorsa indicano la stessa autorità (lo stesso host in ascolto sulla stessa porta UDP). Sono spazi dei nomi distinti e sono considerati server di origine distinti.

6.3. Normalization and Comparison Rules (Regole di Normalizzazione e Confronto)

Poiché gli schemi URI "coap" e "coaps" sono conformi alla sintassi generica URI, tali URI sono normalizzati e confrontati secondo l'algoritmo definito in [RFC3986], Sezione 6, utilizzando i valori predefiniti descritti sopra per ogni schema.

Se la porta è uguale alla porta predefinita per uno schema, la forma normale è omettere il sottocomponente port. Allo stesso modo, un componente di percorso vuoto è equivalente a un percorso assoluto di "/", quindi la forma normale è fornire un percorso di "/". Lo schema e l'host non fanno distinzione tra maiuscole e minuscole e sono normalmente forniti in minuscolo; gli IP-literal sono in forma raccomandata [RFC5952]; tutti gli altri componenti sono confrontati in modo sensibile alle maiuscole e minuscole. I caratteri diversi da quelli nel set "reserved" sono equivalenti ai loro byte codificati in percentuale (vedere [RFC3986], Sezione 2.1): la forma normale è non codificarli.

Ad esempio, i seguenti tre URI sono equivalenti e causano la comparsa delle stesse opzioni e valori di opzione nei messaggi 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 (Scomposizione degli URI in Opzioni)

I passaggi per analizzare le opzioni di una richiesta da una stringa |url| sono i seguenti. Questi passaggi portano o all'inclusione di zero o più opzioni Uri-Host, Uri-Port, Uri-Path e Uri-Query nella richiesta o falliscono.

1. Se la stringa |url| non è un URI assoluto ([RFC3986]), allora questo algoritmo fallisce.

2. Risolvere la stringa |url| utilizzando il processo di risoluzione del riferimento definito da [RFC3986]. In questa fase, l'URL è in codifica ASCII [RFC0020], anche se i componenti decodificati saranno interpretati in UTF-8 [RFC3629] dopo i passaggi 5, 8 e 9.

   Nota: Non importa rispetto a cosa viene risolto a questo punto, poiché sappiamo già che è un URL assoluto.

3. Se |url| non ha un componente <scheme> il cui valore, dopo la conversione in minuscolo ASCII, è "coap" o "coaps", allora questo algoritmo fallisce.

4. Se |url| ha un componente <fragment>, allora questo algoritmo fallisce.

5. Se il componente <host> di |url| non rappresenta l'indirizzo IP di destinazione della richiesta come IP-literal o IPv4address, includere un'opzione Uri-Host e lasciare che il valore di tale opzione sia il valore del componente <host> di |url|, convertito in minuscolo ASCII, quindi convertire tutte le codifiche percentuali ("%" seguito da due cifre esadecimali) nei caratteri corrispondenti.

   Nota: Nel caso usuale in cui l'indirizzo IP di destinazione della richiesta è derivato dalla parte host, questo garantisce che l'opzione Uri-Host sia elettiva per la forma reg-name del componente <host>.

6. Se |url| ha un componente <port>, allora sia |port| il valore di quel componente interpretato come intero decimale; altrimenti, sia |port| la porta predefinita per lo schema.

7. Se |port| non è uguale alla porta UDP di destinazione della richiesta, includere un'opzione Uri-Port e lasciare che il valore di tale opzione sia |port|.

8. Se il valore del componente <path> di |url| è vuoto o consiste in un singolo carattere barra (U+002F SOLIDUS "/"), allora passare al passo successivo.

   Altrimenti, per ogni segmento nel componente <path>, includere un'opzione Uri-Path e lasciare che il valore di tale opzione sia il segmento (non includendo i caratteri barra di separazione) dopo aver convertito ogni codifica percentuale ("%" seguito da due cifre esadecimali) nel byte corrispondente.

9. Se |url| ha un componente <query>, allora, per ogni parametro nel componente <query>, includere un'opzione Uri-Query e lasciare che il valore di tale opzione sia il parametro (non includendo il punto interrogativo e i caratteri e commerciale di separazione) dopo aver convertito ogni codifica percentuale nel byte corrispondente.

Si noti che queste regole risolvono completamente qualsiasi codifica percentuale.

6.5. Composing URIs from Options (Composizione di URI dalle Opzioni)

I passaggi per costruire un URI dalle opzioni di una richiesta sono i seguenti. Questi passaggi portano o a un URI o falliscono. In questi passaggi, codificare in percentuale un carattere significa sostituire ciascuno dei suoi byte (codificati UTF-8) con un carattere "%" seguito da due cifre esadecimali che rappresentano il byte, dove le cifre A-F sono in maiuscolo (come definito in [RFC3986], Sezione 2.1; per ridurre la variabilità, la notazione esadecimale nelle codifiche percentuali negli URI CoAP DEVE utilizzare lettere maiuscole). Le definizioni di "unreserved" e "sub-delims" sono adottate da [RFC3986].

1. Se la richiesta è protetta utilizzando DTLS, sia |url| la stringa "coaps://". Altrimenti, sia |url| la stringa "coap://".

2. Se la richiesta include un'opzione Uri-Host, sia |host| il valore di tale opzione, dove tutti i caratteri non ASCII sono sostituiti dalla loro codifica percentuale corrispondente. Se |host| non è un reg-name valido o IP-literal o IPv4address, l'algoritmo fallisce. Se la richiesta non include un'opzione Uri-Host, sia |host| l'IP-literal (utilizzando le convenzioni di [RFC5952]) o IPv4address che rappresenta l'indirizzo IP di destinazione della richiesta.

3. Aggiungere |host| a |url|.

4. Se la richiesta include un'opzione Uri-Port, sia |port| il valore di tale opzione. Altrimenti, sia |port| la porta UDP di destinazione della richiesta.

5. Se |port| non è la porta predefinita per lo schema, aggiungere un singolo carattere U+003A COLON (":") seguito dalla rappresentazione decimale di |port| a |url|.

6. Sia |resource name| la stringa vuota. Per ogni opzione Uri-Path nella richiesta, aggiungere un singolo carattere U+002F SOLIDUS ("/") seguito dal valore dell'opzione a |resource name|, dopo aver convertito qualsiasi carattere che non è nel set "unreserved", o non è nel set "sub-delims", o non è un carattere U+003A COLON (":"), o non è un carattere U+0040 COMMERCIAL AT ("@"), nella sua forma codificata in percentuale.

7. Se |resource name| è la stringa vuota, impostarlo su un singolo carattere U+002F SOLIDUS ("/").

8. Per ogni opzione Uri-Query nella richiesta, aggiungere un singolo carattere U+003F QUESTION MARK ("?") (per la prima opzione) o U+0026 AMPERSAND ("&") (per le opzioni successive) seguito dal valore dell'opzione a |resource name|, dopo aver convertito qualsiasi carattere che non è nel set "unreserved", o non è nel set "sub-delims" (tranne U+0026 AMPERSAND ("&")), o non è un U+003A COLON (":"), o non è un U+0040 COMMERCIAL AT ("@"), o non è un U+002F SOLIDUS ("/"), o non è un carattere U+003F QUESTION MARK ("?"), nella sua forma codificata in percentuale.

9. Aggiungere |resource name| a |url|.

10. Restituire |url|.

Si noti che questi passaggi sono stati progettati per portare a un URI in forma normale (vedere Sezione 6.3).