[riot-notifications] [RIOT-OS/RIOT] Add further description of CoAP resources (#11171)

Leandro Lanzieri notifications at github.com
Wed Mar 13 14:31:09 CET 2019

#### Current situation
Right now our CoAP resources are described in [`coap_resource_t`](http://doc.riot-os.org/structcoap__resource__t.html) structures which include the resource path, the methods it accepts, a pointer to a handler and a context. That is all the information gcoap or nanocoap have about that resource.

With that limited information only a basic payload can be send when registering to a resource directory or when a GET request to `/.well-known/core` is replied. That is, only the paths of the registered resources expressed in [link format](https://tools.ietf.org/html/rfc6690):

/* registration taken from cord_ep example application */
Those resources have no attributes, not metadata and no semantics that might indicate, for instance, that `/sense/temp` is actually a temperature sensor. Something like:
This has consequences like:
- A CoAP client that tries to learn the server API has not enough information to figure out how to use it without out-of-band information (e.g. API documentation).
- A CoAP client that tries to filter resources results from a resource directory has not information to do so, neither has the directory if it tries to accomplish a lookup filtering.

#### Proposal
This issue aims to figure out if we should add this information to CoAP resources, and if yes how we should implement that.

**Some ideas**:
1- Add fields to the `coap_resource_t` structure, that add information about the resource (e.g. `rt`, `sz`, `if`, etc.). This option does not seem escalable and it is really attached to link format.

2- Add a sort of description callback to the `coap_resource_t` with the form of `ssize_t get_resource_desc(uint8_t *buf, size_t maxlen, uint8_t format)` that would be called if defined to describe the resource in detail in a given format. This would entail more effort from the point of view of the resource implementation, but only if a detailed description is wanted. It would also mean more control over the description.

3- Add some description that is resolved in compile time (maybe just a string) that would override the basic `</path/to/resource>` one. This option is not as flexible as (2) but is cheaper. We should figure out how different formats could be handled in this case.

**Things we should keep in mind**:
- Right now only link format is used for the description of the resources (both on `/.well-known/core` and registration to a resource directory) but [that might change in the future](https://tools.ietf.org/html/draft-hartke-t2trg-coral-reef-01).
- Should this descriptions be resolved in compile time or we would like to change them in runtime (e.g. a resource or an operation is not available under certain circumstances)?
- Should the resource handle the description or nanocoap/gcoap modules?
- ...?

### Useful links
- [RFC 6690 - CoRE Link Format](https://tools.ietf.org/html/rfc6690)
- [CoRE Resource Directory draft](https://tools.ietf.org/html/draft-ietf-core-resource-directory-20)

You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190313/144b193c/attachment-0001.html>

More information about the notifications mailing list