0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Type      |  Length = 3   |       Valid Lifetime          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Reserved                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                          RD Address                           +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Fields:

Type:                   38

Length:                 8-bit unsigned integer.  The length of
                        the option in units of 8 bytes.
                        Always 3.

Valid Lifetime:         16-bit unsigned integer.  The length of
                        time in units of 60 seconds (relative to
                        the time the packet is received) that
                        this Resource Directory address is valid.
                        A value of all zero bits (0x0) indicates
                        that this Resource Directory address
                        is not valid anymore.

Reserved:               This field is unused.  It MUST be
                        initialized to zero by the sender and
                        MUST be ignored by the receiver.

RD Address:             IPv6 address of the RD.

Figure 3: Resource Directory Address Option

5. Resource Directory

This section defines the required set of REST interfaces between a Resource Directory (RD) and endpoints. Although the examples throughout this section assume the use of CoAP [RFC7252], these REST interfaces can also be realized using HTTP [RFC7230]. In all definitions in this section, both CoAP response codes (with dot notation) and HTTP response codes (without dot notation) are shown. An RD implementing this specification MUST support the discovery, registration, update, lookup, and removal interfaces defined in this section.

5.1. Content Formats

Resource Directory implementations using this specification MUST support the application/link-format content format (ct=40).

Resource Directories implementing this specification MAY support additional content formats.

Any additional content format supported by a Resource Directory implementing this specification MUST have an equivalent serialization in the application/link-format content format.

5.2. Base URI Discovery

Before an endpoint can make use of an RD, it must first know the RD’s address and port, and the base URI information for its REST API. This section defines discovery of the RD and its base URI using the well-known interface of the CoRE Link Format [RFC6690]. It is however expected that RDs will also be discoverable via other methods depending on the deployment.

Discovery of the RD base URI is performed by sending either a multicast or unicast GET request to /.well-known/core and including a Resource Type (rt) parameter [RFC6690] with the value “core.rd” in the query string. Likewise, a Resource Type parameter value of “core.rd-lookup*” is used to discover the base URI for RD Lookup operations, and “core.gp” is used to discover the base URI for RD Group operations. Upon success, the response will contain a payload with a link format entry for each RD function discovered, indicating the base URI of the RD function returned and the corresponding Resource Type. When performing multicast discovery, the multicast IP address used will depend on the scope required and the multicast capabilities of the network.

A Resource Directory MAY provide hints about the content-formats it supports in the links it exposes or registers, using the “ct” link attribute, as shown in the example below. Clients MAY use these hints to select alternate content-formats for interaction with the Resource Directory.

HTTP does not support multicast and consequently only unicast discovery can be supported using HTTP. Links to Resource Directories MAY be registered in other Resource Directories, and well-known entry points SHOULD be provided to enable the bootstrapping of unicast discovery.

An RD implementation of this specification MUST support query filtering for the rt parameter as defined in [RFC6690].

The discovery request interface is specified as follows:

Interaction:

EP -> RD

Method:

GET

URI Template:

/.well-known/core{?rt}

URI Template Variables:

rt :=

Resource Type (optional). MAY contain one of the values “core.rd”, “core.rd-lookup*”, “core.rd-lookup-d”, “core.rd-lookup-res”, “core.rd-lookup-ep”, “core.rd-lookup-gp”, “core.rd-group” or “core.rd*”

Content-Format:

application/link-format (if any)

Content-Format:

application/link-format+json (if any)

Content-Format:

application/link-format+cbor (if any)

The following response codes are defined for this interface:

Success:

2.05 “Content” with an application/link-format, application/link-format+json, or application/link-format+cbor payload containing one or more matching entries for the RD resource.

Failure:

4.04 “Not Found” is returned in case no matching entry is found for a unicast request.

Failure:

4.00 “Bad Request” is returned in case of a malformed request for a unicast request.

Failure:

No error response to a multicast request.

HTTP support :

YES (Unicast only)

The following example shows an endpoint discovering an RD using this interface, thus learning that the base RD resource is, in this example, at /rd and that the content-format delivered by the server hosting the resource is application/link-format (ct=40). Note that it is up to the RD to choose its base RD resource, although diagnostics and debugging is facilitated by using the base paths specified here where possible.

Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*

Res: 2.05 Content
</rd>;rt="core.rd";ct=40,
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40,
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40",
</rd-group>;rt="core.rd-group";ct=40

The following example shows the way of indicating that a client may request alternate content-formats. The Content-Format code attribute “ct” MAY include a space-separated sequence of Content-Format codes as specified in Section 7.2.1 of [RFC7252], indicating that multiple content-formats are available. The example below shows the required Content-Format 40 (application/link-format) indicated as well as a more application-specific content format (picked as 65225 in this example; this is in the experimental space, not an assigned value). The base RD resource values /rd, /rd-lookup, and /rd-group are example values.

Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*

Res: 2.05 Content
</rd>;rt="core.rd";ct="40 65225",
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40 65225",
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 65225",
</rd-group>;rt="core.rd-group";ct="40 65225"

5.3. Registration

After discovering the location of an RD, an endpoint MAY register its resources using the registration interface. This interface accepts a POST from an endpoint containing the list of resources to be added to the directory as the message payload in the CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link-format+json), or CBOR CoRE Link Format (application/link-format+cbor) [I-D.ietf-core-links-json], along with query parameters indicating the name of the endpoint, and optionally its domain and the lifetime of the registration. It is expected that other specifications will define further parameters (see Section 9.3). The RD then creates a new registration resource in the RD and returns its location. An endpoint MUST use that location when refreshing registrations using this interface. Endpoint resources in the RD are kept active for the period indicated by the lifetime parameter. The endpoint is responsible for refreshing the entry within this period using either the registration or update interface. The registration interface MUST be implemented to be idempotent, so that registering twice with the same endpoint parameters ep and d does not create multiple RD entries. A new registration may be created at any time to supersede an existing registration, replacing the registration parameters and links.

The registration request interface is specified as follows:

Interaction:

EP -> RD

Method:

POST

URI Template:

/{+rd}{?ep,d,et,lt,con}

URI Template Variables:

rd :=

RD Base URI path (mandatory). This is the path of the RD, as obtained from discovery. The value “rd” is recommended for this variable.

ep :=

Endpoint name (mandatory). The endpoint name is an identifier that MUST be unique within a domain. The maximum length of this parameter is 63 bytes.

d :=

Domain (optional). The domain to which this endpoint belongs. The maximum length of this parameter is 63 bytes. When this parameter is elided, the RD MAY associate the endpoint with a configured default domain.

et :=

Endpoint Type (optional). The semantic type of the endpoint. This parameter SHOULD be less than 63 bytes.

lt :=

Lifetime (optional). Lifetime of the registration in seconds. Range of 60-4294967295. If no lifetime is included in the initial registration, a default value of 86400 (24 hours) SHOULD be assumed. If the lt parameter is not included in a registration refresh or update operation, the most recently supplied value SHALL be re-used.

con :=

Context (optional). This parameter sets the scheme, address and port at which this server is available in the form scheme://host:port/path. In the absence of this parameter the scheme of the protocol, source address and source port of the register request are assumed. This parameter is mandatory when the directory is filled by a third party such as an commissioning tool. When con is used, scheme and host are mandatory and port and path parameters are optional. If the endpoint uses an ephemeral port to register with, it MUST include the con: parameter in the registration to provide a valid network path. If the endpoint which is located behind a NAT gateway is registering with a Resource Directory which is on the network service side of the NAT gateway, the endpoint MUST use a persistent port for the outgoing registration in order to provide the NAT gateway with a valid network address for replies and incoming requests.

Content-Format:

application/link-format

Content-Format:

application/link-format+json

Content-Format:

application/link-format+cbor

The following response codes are defined for this interface:

Success:

2.01 “Created” or 201 “Created”. The Location header option MUST be included in the response when a new registration resource is created. This Location MUST be a stable identifier generated by the RD as it is used for all subsequent operations on this registration resource. The registration resource location thus returned is for the purpose of updating the lifetime of the registration and for maintaining the content of the registered links, including updating and deleting links.

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.09 “Conflict” or 409 “Conflict”. Attempt to update the registration content with links resulting in plurality of references; see Section 5.3.4.

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support:

YES

The following example shows an endpoint with the name “node1” registering two resources to an RD using this interface. The location “/rd” is an example value of an RD base location.

Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor"

Res: 2.01 Created
Location: /rd/4521

A Resource Directory may optionally support HTTP. Here is an example of the same registration operation above, when done using HTTP.

Req: POST /rd?ep=node1 HTTP/1.1
Host : example.com
Content-Type: application/link-format
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor"

Res: 201 Created
Location: /rd/4521

5.3.1. Simple Registration

Not all endpoints hosting resources are expected to know how to upload links to a RD as described in Section 5.3. Instead, simple endpoints can implement the Simple Registration approach described in this section. An RD implementing this specification MUST implement Simple Registration. However, there may be security reasons why this form of directory discovery would be disabled.

This approach requires that the endpoint makes available the hosted resources that it wants to be discovered, as links on its /.well-known/core interface as specified in [RFC6690].

The endpoint then finds one or more addresses of the directory server as described in Section 4.

An endpoint can send (a selection of) hosted resources to a directory server for publication as described in Section 5.3.2.

The directory server integrates the information it received this way into its resource directory. It MAY make the information available to further directories, if it can ensure that a loop does not form. The protocol used between directories to ensure loop-free operation is outside the scope of this document.

5.3.2. Simple publishing to Resource Directory Server

An endpoint that wants to make itself discoverable occasionally sends a POST request to the /.well-known/core URI of any candidate directory server that it finds. The body of the POST request is empty, which triggers the resource directory server to perform GET requests at the requesting server’s default discovery URI to obtain the link-format payload to register.

The endpoint MUST include the endpoint name and MAY include the registration parameters d, lt, and et, in the POST request as per Section 5.3.

The following example shows an endpoint using simple publishing, by simply sending an empty POST to a resource directory.

Req:(to RD server from [ff02::1])
POST coap://rd.example.com/.well-known/core?lt=6000;ep=node1

Content-Format: 40

payload:

(empty payload)

Res: 2.04 Changed

(later)

Req: (from RD server to [ff02::1])
GET coap://[ff02::1]/.well-known/core

Accept: 40

Res: 2.05 Content

payload:

</sen/temp>

5.3.3. Third-party registration

For some applications, even Simple Directory Discovery may be too taxing for certain very constrained devices, in particular if the security requirements become too onerous.

In a controlled environment (e.g. building control), the Resource Directory can be filled by a third device, called a commissioning tool. The commissioning tool can fill the Resource Directory from a database or other means. For that purpose the scheme, IP address and port of the registered device is indicated in the Context parameter of the registration described in Section 5.3.

5.3.4. Plurality of link references in a Registration

Plurality of link references within a Registration (registration resource) is an indication of some error condition and should not be allowed.

Plurality of link references exists if, and only if, two or more links in a Registration contain identical context, target, and relation values. This condition would be likely to arise if there were multiple co-ordinators or configuration tools, each with a different set of configuration values for the same resource.

A Resource Directory SHOULD reject a registration, or an operation on a registration, which would result in a plurality of link references within the the context of the registration. There is no requirement in this document for a resource directory to check for plurality of reference between different registrations. Resource Directory operations which are rejected due to reference plurality SHOULD be returned the “Conflict” code, indicating that there is someting wrong with the request.

5.4. Operations on the Registration Resource

After the initial registration, an endpoint should retain the returned location of the Registration Resource for further operations, including refreshing the registration in order to extend the lifetie and “keep-alive” the registration. If the lifetime of the registration expires, the RD SHOULD NOT respond to discovery queries with information from the endpoint. The RD SHOULD continue to provide access to the Registration Resource after a registration time-out occurs in order to enable the registering endpoint to eventually refresh the registration. The RD MAY eventually remove the registration resource for the purpose of resource recovery and garbage collection. If the Registration Resource is removed, the endpoint will need to re-register.

The Registration Resource may also be used to inspect the registration resource using GET, update the registration link contents using PATCH, or cancel the registration using DELETE.

These operations are described in this section.

In accordance with Section 5.3.4, operations which would result in plural link references within the context of a registration resource SHOULD be rejected using the “Conflict” result code.

5.4.1. Registration Update

The update interface is used by an endpoint to refresh or update its registration with an RD. To use the interface, the endpoint sends a POST request to the registration resource returned in the Location header option in the response returned from the intial registration operation.

An update MAY update the lifetime or context registration parameters “lt”, “con” as in Section 5.3 ) if the previous settings are to be retained. Parameters that are not being changed changed SHOULD NOT be included in an update. Adding parameters that have not changed increases the size of the message but does not have any other implications. Parameters MUST be included as query parameters in an update operation as in Section 5.3.

Upon receiving an update request, an RD MUST reset the timeout for that endpoint and update the scheme, IP address and port of the endpoint, using the source address of the update, or the context (“con”) parameter if present. If the lifetime parameter “lt” is included in the received update request, the RD MUST update the lifetime of the registration and set the timeout equal to the new lifetime. If the lifetime parameter is not included in the registration update, the most recent setting is re-used for the next registration time-out period.

An update MAY optionally add or replace links for the endpoint by including those links in the payload of the update as a CoRE Link Format document. A link is replaced only if all of the target URI and relation type (if present) and anchor value (if present) match.

If the link payload is included, it SHOULD be checked for reference plurality as described in Section 5.3.4 and rejected with a “Conflict” result if there are plural link references detected.

In addition to the use of POST, as described in this section, there is an alternate way to add, replace, and delete links using PATCH as described in Section 5.4.4.

The update registration request interface is specified as follows:

Interaction:

EP -> RD

Method:

POST

URI Template:

/{+location}{?lt,con}

URI Template Variables:

location :=

This is the Location path returned by the RD as a result of a successful earlier registration.

lt :=

Lifetime (optional). Lifetime of the registration in seconds. Range of 60-4294967295. If no lifetime is included, the previous last lifetime set on a previous update or the original registration (falling back to 86400) SHOULD be used.

con :=

Context (optional). This parameter sets the scheme, address and port at which this server is available in the form scheme://host:port/path. In the absence of this parameter the scheme of the protocol, source address and source port of the register request are assumed. This parameter is mandatory when the directory is filled by a third party such as an commissioning tool. When con is used, scheme and host are mandatory and port and path parameters are optional.

Content-Format:

application/link-format (mandatory)

Content-Format:

application/link-format+json (optional)

Content-Format:

application/link-format+cbor (optional)

The following response codes are defined for this interface:

Success:

2.04 “Changed” or 204 “No Content” if the update was successfully processed.

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. Registration does not exist (e.g. may have expired).

Failure:

4.09 “Conflict” or 409 “Conflict”. Attempt to update the registration content with links resulting in plurality of references; see Section 5.3.4.

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support:

YES

The following example shows an endpoint updating its registration at an RD using this interface with the example location value: /rd/4521.

Req: POST /rd/4521

Res: 2.04 Changed

The following example shows an endpoint updating its registration with a new lifetime and context, changing an existing link, and adding a new link using this interface with the example location value /rd/4521. With the initial registration the client set the following values:

• lifetime (lt)=500
• context (con)=coap://local-proxy-old.example.com:5683
• resource= </sensors/temp>;ct=41;rt=”foobar”;if=”sensor”

Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683"
Content-Format: 40
Payload:
</sensors/temp>;ct=41;rt="temperature-f";if="sensor",
</sensors/door>;ct=41;rt="door";if="sensor"

Res: 2.04 Changed

5.4.2. Registration Removal

Although RD entries have soft state and will eventually timeout after their lifetime, an endpoint SHOULD explicitly remove its entry from the RD if it knows it will no longer be available (for example on shut-down). This is accomplished using a removal interface on the RD by performing a DELETE on the endpoint resource.

The removal request interface is specified as follows:

Interaction:

EP -> RD

Method:

DELETE

URI Template:

/{+location}

URI Template Variables:

location :=

This is the Location path returned by the RD as a result of a successful earlier registration.

The following responses codes are defined for this interface:

Success:

2.02 “Deleted” or 204 “No Content” upon successful deletion

Failure:

4.00 “Bad Request” or 400 “Bad request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. Registration does not exist (e.g. may have expired).

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support: YES

The following examples shows successful removal of the endpoint from the RD with example location value /rd/4521.

Req: DELETE /rd/4521

Res: 2.02 Deleted

5.4.3. Read Endpoint Links

Some endpoints may wish to manage their links as a collection, and may need to read the current set of links stored in the registration resource, in order to determine link maintenance operations.

One or more links MAY be selected by using query filtering as specified in [RFC6690] Section 4.1

If no links are selected, the Resource Directory SHOULD return an empty payload.

The read request interface is specified as follows:

Interaction:

EP -> RD

Method:

GET

URI Template:

/{+location}{?href,rel,rt,if,ct}

URI Template Variables:

location :=

This is the Location path returned by the RD as a result of a successful earlier registration.

href,rel,rt,if,ct := link relations and attributes specified in the query in order to select particular links based on their relations and attributes. “href” denotes the URI target of the link. See [RFC6690] Sec. 4.1

The following responses codes are defined for this interface:

Success:

2.05 “Content” or 200 “OK” upon success with an application/link-format, application/link-format+cbor, or application/link-format+json payload.

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. Registration does not exist (e.g. may have expired).

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support: YES

The following examples show successful read of the endpoint links from the RD, with example location value /rd/4521.

Req: GET /rd/4521

Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor"

5.4.4. Update Endpoint Links

A PATCH update adds, removes or changes links for the endpoint by including link update information in the payload of the update as a merge-patch+json format [RFC7396] document.

Other PATCH document formats may be used as appropriate for patching the array of objects format of a Registration Resource. In particular, a select-merge patch document format could combine the function of link selection query and link attribute replacement values.

One or more links are selected for update by using query filtering as specified in [RFC6690] Section 4.1

The query filter selects the links to be modified or deleted, by matching the query parameter values to the values of the link attributes.

When the query parameters are not present in the request, the payload specifies links to be added to the target document. When the query parameters are present, the attribute names and values in the query parameters select one or more links on which to apply the PATCH operation.

If no links are selected by the query parameters, the PATCH operation SHOULD NOT update the state of any resource, and SHOULD return a reply of “Changed”.

If an attribute name specified in the PATCH document exists in any the set of selected links, all occurrences of the attribute value in the target document MUST be updated using the value from the PATCH payload. If the attribute name is not present in any selected links, the attribute MUST be added to the links.

If the PATCH payload contains plural link references, or processing the PATCH payload would result in plural link references, the request SHOULD be rejected with a “Conflict” result.

If the PATCH payload results in the modification of link target, context, or relation values, that is “href”, “rel”, or “anchor”, the request SHOULD be rejected with a “Conflict” result code.

The update request interface is specified as follows:

Interaction:

EP -> RD

Method:

PATCH

URI Template:

/{+location}{?href,rel,rt,if,ct}

URI Template Variables:

location :=

This is the Location path returned by the RD as a result of a successful earlier registration.

href,rel,rt,if,ct := link relations and attributes specified in the query in order to select particular links based on their relations and attributes. “href” denotes the URI target of the link. See [RFC6690] Sec. 4.1

Content-Format:

application/merge-patch+json (mandatory)

The following response codes are defined for this interface:

Success:

2.04 “Changed” 0r 204 “No Content” in the update was successfully processed.

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. Registration resource does not exist (e.g. may have expired).

Failure:

4.09 “Conflict” or 409 “Conflict”. Attempt to update the registration content with links resulting in plurality of references; see Section 5.3.4.

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support: YES

The following examples show an endpoint adding </sensors/humid>, modifying </sensors/temp>, and removing </sensors/light> links in RD using the Update Endpoint Links function with the example location value /rd/4521.

The Registration Resource initial state is:

Req: GET /rd/4521

Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature",
</sensors/light>;ct=41;rt="light-lux";if="sensor"

The following example shows an EP adding the link </sensors/humid>;ct=41;rt=”humid-s”;if=”sensor” to the collection of links at the location /rd/4521.

Req: PATCH /rd/4521

Payload:
[{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}]

Content-Format:
application/merge-patch+json

Res: 2.04 Changed

Req: GET /rd/4521

Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature",
</sensors/light>;ct=41;rt="light-lux";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"

The following example shows an EP modifying all links at the example location /rd/4521 which are identified by href=”/sensors/temp”, from the initial link-value of </sensors/temp>;rt=”temperature” to the new link-value </sensors/temp>;rt=”temperature-c”;if=”sensor” by changing the value of the link attribute “rt” and adding the link attribute if=”sensor” using the PATCH operation with the supplied merge-patch+json document payload.

Req: PATCH /rd/4521?href=/sensors/temp

Payload:
{"rt": "temperature-c", "if": "sensor"},

Content-Format:
application/merge-patch+json

Res: 2.04 Changed

Req: GET /rd/4521

Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"

This example shows an EP removing all links at the example location /rd/4521 which are identified by href=”/sensors/light”.

Req: PATCH /rd/4521?href=/sensors/light

Payload:
{}

Content-Format:
application/merge-patch+json

Res: 2.04 Changed

Req: GET /rd/4521

Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"

6. RD Groups

This section defines the REST API for the creation, management, and lookup of endpoints for group operations. Similar to endpoint registration entries in the RD, groups may be created or removed. However unlike an endpoint entry, a group entry consists of a list of endpoints and does not have a lifetime associated with it. In order to make use of multicast requests with CoAP, a group MAY have a multicast address associated with it.

6.1. Register a Group

In order to create a group, a commissioning tool (CT) used to configure groups, makes a request to the RD indicating the name of the group to create (or update), optionally the domain the group belongs to, and optionally the multicast address of the group. The registration message includes the list of endpoints that belong to that group.

All the endpoints in the group MUST be registered with the RD before registering a group. If an endpoint is not yet registered to the RD before registering the group, the registration message returns an error. The RD sends a blank target URI for every endpoint link when registering the group.

Configuration of the endpoints themselves is out of scope of this specification. Such an interface for managing the group membership of an endpoint has been defined in [RFC7390].

The registration request interface is specified as follows:

Interaction:

CT -> RD

Method:

POST

URI Template:

/{+rd-group}{?gp,d,con}

URI Template Variables:

rd-group :=

RD Group Base URI path (mandatory). This is the path of the RD Group REST API. The value “rd-group” is recommended for this variable.

gp :=

Group Name (mandatory). The name of the group to be created or replaced, unique within that domain. The maximum length of this parameter is 63 bytes.

d :=

Domain (optional). The domain to which this group belongs. The maximum length of this parameter is 63 bytes. Optional. When this parameter is elided, the RD MAY associate the endpoint with a configured default domain.

con :=

Context (optional). This parameter sets the scheme, address and port at which this server is available in the form scheme://host:port/path. In the absence of this parameter the scheme of the protocol, source address and source port of the register request are assumed. This parameter is mandatory when the directory is filled by a third party such as an commissioning tool. When con is used, scheme and host are mandatory and port and path parameters are optional.

Content-Format:

application/link-format

Content-Format:

application/link-format+json

Content-Format:

application/link-format+cbor

The following response codes are defined for this interface:

Success:

2.01 “Created” or 201 “Created”. The Location header option MUST be returned in response to a successful group CREATE operation. This Location MUST be a stable identifier generated by the RD as it is used for delete operations of the group registration resource.

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. An Endpoint is not registered in the RD (e.g. may have expired).

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support:

YES

The following example shows an EP registering a group with the name “lights” which has two endpoints to an RD using this interface. The base location value /rd-group is an example of an RD base location.

Req: POST coap://rd.example.com/rd-group?gp=lights
Content-Format: 40
Payload:
<>;ep="node1",
<>;ep="node2"

Res: 2.01 Created
Location: /rd-group/12

6.2. Group Removal

A group can be removed simply by sending a removal message to the location of the group registration resource which was returned when intially registering the group. Removing a group MUST NOT remove the endpoints of the group from the RD.

The removal request interface is specified as follows:

Interaction:

CT -> RD

Method:

DELETE

URI Template:

/{+location}

URI Template Variables:

location :=

This is the Location path returned by the RD as a result of a successful group registration.

The following responses codes are defined for this interface:

Success:

2.02 “Deleted” or 204 “No Content” upon successful deletion

Failure:

4.00 “Bad Request” or 400 “Bad Request”. Malformed request.

Failure:

4.04 “Not Found” or 404 “Not Found”. Group does not exist.

Failure:

5.03 “Service Unavailable” or 503 “Service Unavailable”. Service could not perform the operation.

HTTP support:

YES

The following examples shows successful removal of the group from the RD with the example location value /rd-group/12.

Req: DELETE /rd-group/12

Res: 2.02 Deleted

7. RD Lookup

In order for an RD to be used for discovering resources registered with it, an optional lookup interface may be provided. This lookup interface is defined as a default, and it is assumed that RDs may also support lookups to return resource descriptions in alternative formats (e.g. Atom or HTML Link) or using more advanced interfaces (e.g. supporting context or semantic based lookup).

RD Lookup allows lookups for domains, groups, endpoints and resources using attributes defined in this document and for use with the CoRE Link Format. The result of a lookup request is the list of links (if any) corresponding to the type of lookup. Thus, a domain lookup MUST return a list of domains, a group lookup MUST return a list of groups, an endpoint lookup MUST return a list of endpoints and a resource lookup MUST return a list of links to resources.

RD Lookup does not expose registration resources directly, but returns link content from registration resource entries which satisfy RD Lookup queries.

The lookup type is selected by a URI endpoint, which is indicated by a Resource Type as per Table 1 below:

Req: GET /rd-lookup/res?rt=temperature

Res: 2.05 Content
<coap://[FDFD::123]:61616/temp>;rt="temperature"

Req: GET /rd-lookup/ep?et=power-node

Res: 2.05 Content
<coap://[FDFD::127]:61616>;ep="node5",
<coap://[FDFD::129]:61616>;ep="node7"

Req: GET /rd-lookup/d

Res: 2.05 Content
<>;d="domain1",
<>;d="domain2"

Req: GET /rd-lookup/gp

Res: 2.05 Content
<>;gp="lights1";d="example.com"
<>;gp="lights2";d="ecample.com"

Req: GET /rd-lookup/ep?gp=lights1

Res: 2.05 Content
<coap://[FDFD::123]:61616>;ep="node1",
<coap://[FDFD::124]:61616>;ep="node2"

Req: GET /rd-lookup/gp?ep=node1

Res: 2.05 Content
<>;gp="lights1"

Req: GET /rd-lookup/res?page=0&count=5

Res: 2.05 Content
<coap://[FDFD::123]:61616/res/0>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/1>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/2>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/3>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/4>;rt=sensor;ct=60

Req: GET /rd-lookup/res?page=1&count=5

Res: 2.05 Content
<coap://[FDFD::123]:61616/res/5>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/6>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/7>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/8>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/9>;rt=sensor;ct=60

Req: POST coap://[FDFD::ABCD:0]/rd
  ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1]
Payload:
</light/left>;rt="light"; d="R2-4-015",
</light/middle>;rt="light"; d="R2-4-015",
</light/right>;rt="light";d="R2-4-015"

Res: 2.01 Created
Location: /rd/4521

Req: POST coap://[FDFD::ABCD:0]/rd
  ?ep=lm_R2-4-015_door&con=coap://[FDFD::ABCD:2]
Payload:
</light/left>;rt="light"; d="R2-4-015",
</light/middle>;rt="light"; d="R2-4-015",
</light/right>;rt="light"; d="R2-4-015"

Res: 2.01 Created
Location: /rd/4522

Req: POST coap://[FDFD::ABCD:0]/rd
  ?ep=ps_R2-4-015_door&con=coap://[FDFD::ABCD:3]
Payload:
</ps>;rt="p-sensor"; d="R2-4-015"

Res: 2.01 Created
Location: /rd/4523

Req: POST coap://[FDFD::ABCD:0]/rd-group
?gp=grp_R2-4-015;con="coap//[FF05::1]"
Payload:
<>ep=lm_R2-4-015_wndw,
<>ep=lm_R2-4-015_door,
<>ep=ps_R2-4-015_door

Res: 2.01 Created
Location: /rd-group/501

Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep
  ?d=R2-4-015;rt=light

Res: 2.05 Content
<coap://[FDFD::ABCD:1]>;
  ep="lm_R2-4-015_wndw",
<coap://[FDFD::ABCD:2]>;
   ep="lm_R2-4-015_door"

Req: GET coap://[FDFD::ABCD:0]/rd-lookup/gp
  ?ep=lm_R2-4-015_wndw

Res: 2.05 Content
<coap://[FF05::1]>;gp="grp_R2-4-015"

Req: POST //[FDFD::ABCD:1]/coap-group
          Content-Format: application/coap-group+json
       { "a": "[FF05::1]",
          "n": "grp_R2-4-015"}

Res: 2.01 Created
Location-Path: /coap-group/1

/1/0/1

ep - Endpoint Name
lt - registration lifetime

et - Endpoint Type
con - Context

</1>,</1/0>,</3/0>,</5>

lt - Registration Lifetime
b - Protocol Binding
sms - MSISDN
link payload - new or modified links