Current situation

Right now our CoAP resources are described in coap_resource_t 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:

/* registration taken from cord_ep example application */
</node/info>,</sense/hum>,</sense/temp>

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:

</sense/temp>;rt="http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature";
if="http://www.example.org/myapp.wadl#sensor"

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.

[EDIT]
4- (Proposed by @kaspar030 here) Turn the "request handlers" into "resource handlers" and add "virtual" methods. That way the same callback can describe the resource in a given format if requested. Also addresses the issue of dynamically generated description. It would look like:

/**     
 * @brief   Resource handler type     
 */     
-typedef ssize_t (*coap_handler_t)(coap_pkt_t *pkt, uint8_t *buf, size_t len, void *context);
+typedef ssize_t (*coap_handler_t)(coap_pkt_t *pkt, uint32_t method, uint8_t *buf, size_t len, void *context);

Then a handler could be defined with:

{ "/node/info",  COAP_GET | COAP_LINK_FORMAT, _handler_info, NULL },

int _handler_info(pkt, method, buf, len, context) {
if (method==COAP_LINK_FORMAT) {
  // write link format to buf
}
...
}

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.
• 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
• CoRE Resource Directory draft