Web of Things (WoT) Discovery

8.2.2.1 Registration

The Registration API is a RESTful HTTP API in accordance with the recommendations defined in [ RFC7231 ] and [ REST-IOT ]. The default serialization format for all request and response bodies MUST be JSON, with JSON-LD 1.1 [ JSON-LD11 ] syntax to support extensions and semantic processing. Directories MAY accept additional representations based on request's indicated Content-Type or Content-Encoding, and provide additional representations through server-driven content negotiation.

The Registration API MUST provide create, retrieve, update, delete (CRUD) interfaces based on the following specification:

Create a TD:

The API MUST allow registration of a TD object passed as request body. The request SHOULD contain application/td+json Content-Type header for JSON serialization of TD. The TD object SHOULD be validated syntactically using the Thing Description JSON Schema [ WoT-Thing-Description ].

A TD which is identified with an id attribute MUST be handled differently with one that has no identifier ( Anonymous TD ). The create operations are specified as createTD action in Directory's Thing Description and elaborated below:

• A TD MUST be submitted to the directory using an HTTP PUT request at a target location (HTTP path) containing the unique TD id . Upon successful processing, the server MUST respond with 201 (Created) status.

  Note: If the target location corresponds to an existing TD, the request shall instead proceed as an Update operation and respond the appropriate status code (see Update section).

• An Anonymous TD MUST be submitted to the directory using an HTTP POST request. Upon successful processing, the server MUST respond with 201 (Created) status and a Location header containing a system-generated identifier for the TD. The identifier SHOULD be a Version 4 UUID URN [ RFC4122 ].

Error responses:

• 400 (Bad Request): Invalid serialization or TD. This is accompanied by an appropriate response message.
• 401 (Unauthorized): No authentication.
• 403 (Forbidden): Insufficient rights to the resource.

Retrieve a TD:

A TD MUST be retrieved from the directory using an HTTP GET request, including the identifier of the TD as part of the path. A successful response MUST have 200 (OK) status, contain application/td+json Content-Type header, and the requested TD in body. The retrieve operation is specified as retrieveTD property in Directory's Thing Description .

Error responses:

• 404 (Not Found): TD with the given id not found.
• 401 (Unauthorized): No authentication.
• 403 (Forbidden): Insufficient rights to the resource.

Update a TD:

The API MUST allow modifications to existing TDs as full replacement or partial updates. The request SHOULD contain application/td+json Content-Type header for JSON serialization of TD. The update operations are described below:

• A modified TD MUST replace an existing one when submitted using an HTTP PUT request to the location corresponding to the existing TD. The TD object SHOULD be validated syntactically using the Thing Description JSON Schema [ WoT-Thing-Description ]. Upon success, the server MUST respond with 204 (No Content) status. This operation is specified as updateTD property in Directory's Thing Description .

  Note: If the target location does not correspond to an existing TD, the request shall instead proceed as a Create operation and respond the appropriate status code (see Create section). In other words, an HTTP PUT request acts as a create or update operation. An HTTP PATCH may be used for an update-only operation.

• An existing TD MUST be partially modified when the modified parts are submitted using an HTTP PATCH request to the location corresponding to the existing TD. The modified parts MUST conform to the original TD structure. The input MAY include other existing parts of the TD or the whole TD object. When the whole TD object is provided as input, the operation acts as an update-only action. After applying the modifications, the TD object SHOULD be validated syntactically using the Thing Description JSON Schema [ WoT-Thing-Description ]. Upon success, the server MUST respond with a 204 (No Content) status. This operation is specified as updatePartialTD property in Directory's Thing Description .

Error responses:

• 400 (Bad Request): Invalid serialization or TD. This is accompanied by an appropriate response message.
• 404 (Not Found): TD with the given id not found (for PATCH only).
• 401 (Unauthorized): Rejecting a request without appropriate authentication.
• 403 (Forbidden): Rejecting a request due to insufficient rights to the resource.

Delete a TD:

A TD MUST be removed from the directory when an HTTP DELETE request is submitted to the location corresponding to the existing TD. A successful response MUST have 204 (No Content) status. The retrieve operation is specified as deleteTD property in Directory's Thing Description .

Error responses:

• 404 (Not Found): TD with the given id not found.
• 401 (Unauthorized): No authentication.
• 403 (Forbidden): Insufficient rights to the resource.

8.2.2.2 Management

Other administrative functions not having to do with CRUD of individual records, for example, security configuration. Also, administrator roles may expand the capabilities of administrators for management of records (for instance, the ability to delete a record they did not create).

8.2.2.3 Notification

Sub-API to notify clients of events, such as updates to TDs.

8.2.2.4 Search

Sub-API to search a directory, e.g. issue a query. There are different forms and levels of query possible, for example, syntactic (JSONPath, XPath) vs. semantic (SPARQL), and the more advanced query types may not be supported by all directories. So this API will have further subsections, some of which will be optional. Search also includes a sub-API for managing listing the contents (eg returned by a query) including handling pagination, etc. Note that one special form of query will be able to return everything. Results may be subject to the requestor's authorization.

To discuss further:

• Federated queries to other TDDs
• Spatial and network-limited queries
• Links