From 69b211933d4a9ac47a77f39b3d8b6c50f4561125 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Fri, 11 Feb 2022 17:32:48 +0100 Subject: [PATCH 01/17] Things API draft --- index.html | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 66a28289..4bd3dbc0 100755 --- a/index.html +++ b/index.html @@ -893,10 +893,23 @@

Registration

- - The Registration API MUST provide interfaces to - create, retrieve, update, delete, and list (CRUDL) TDs. - + + The Things API provides interfaces to + create, retrieve, update, delete, and list (CRUDL) TDs. + + It is MANDATORY to implement the interface to list TDs. + Useful for static directories. + Useful when other operations are available via non-HTTP protocols. + Filtering provided via search API. + It is recommended that the + create, retrieve, update, delete (CRUD) interfaces are + provided together. + Need to update the TM. + + + + + The operations are described below:

From dee8609b57604e2969a973c1519aa23d4f8c0cd4 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Sat, 12 Feb 2022 19:25:31 +0100 Subject: [PATCH 02/17] Update intro and existing assertions --- directory.tm.json | 3 ++ index.html | 84 ++++++++++++++++++++++++++++------------------- 2 files changed, 53 insertions(+), 34 deletions(-) diff --git a/directory.tm.json b/directory.tm.json index cbafd1f6..d7886069 100755 --- a/directory.tm.json +++ b/directory.tm.json @@ -12,6 +12,9 @@ "model": "1.0.0-alpha" }, "base": "{{DIRECTORY_BASE_URL}}", + "tm:required": [ + "#/properties/things" + ], "properties": { "things": { "description": "Retrieve all Thing Descriptions", diff --git a/index.html b/index.html index 4bd3dbc0..9e30b73e 100755 --- a/index.html +++ b/index.html @@ -877,15 +877,19 @@

Directory Service API

-

Registration

+

Things API

- The Registration API is a RESTful HTTP API in accordance with the recommendations + The Things API is a RESTful HTTP API served at the `/things` endpoint. + The design of this API is in accordance with the recommendations defined in [[RFC7231]] and [[?REST-IOT]]. +

+

The default serialization format for all request and success response bodies MUST be JSON, with JSON-LD 1.1 [[JSON-LD11]] syntax to support extensions and semantic processing. + Certain applications may require serializations other than JSON. Directories MAY accept additional representations based on request's indicated Content-Type or Content-Encoding, and provide additional representations through @@ -896,34 +900,34 @@

Registration

The Things API provides interfaces to create, retrieve, update, delete, and list (CRUDL) TDs. +

+

+ Implementing the interface to list TDs over HTTP is REQUIRED. - It is MANDATORY to implement the interface to list TDs. - Useful for static directories. - Useful when other operations are available via non-HTTP protocols. - Filtering provided via search API. - It is recommended that the - create, retrieve, update, delete (CRUD) interfaces are - provided together. - Need to update the TM. - - - + All other create, retrieve, update, and delete (CRUD) interfaces are OPTIONAL. +

+

+ For directories that serve the resources from a static collection, + it is practical to only implement interfaces to list and retrieve TDs + but not to create, update, and delete. + This is also useful for directories that only intend to expose + retrieval over HTTP, and allow other operations over non-HTTP protocols. - - + For other directories, it is recommended to implement list, as well as the + four CRUD interfaces. + Additional control over the CRUD interfaces should + be enforced via access control mechanisms. +

+

The operations are described below:

Creation

- - 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. - + Creation refers to the registration of a new TD inside the directory. +

+

The TD object is validated in accordance with [[[#validation]]]. Note that a TD may or may not be generated by the Thing it describes. For brownfield devices in particular a separate Discoverer process @@ -940,9 +944,16 @@

Creation

  • - A TD MUST be submitted to the directory using an HTTP `PUT` request - at `/things/{id}` endpoint, where `id` is the unique TD identifier. + A TD MUST be submitted to the directory in the body of an HTTP `PUT` request + at `/things/{id}` endpoint, where `id` is the unique TD identifier, + present inside the TD object. + An Anonymous TD is handled differently; see below. + + The request SHOULD contain `application/td+json` Content-Type header for + JSON serialization of TD. + + The TD object is validated in accordance with [[[#validation]]]. Upon successful processing, the server MUST respond with 201 (Created) status. @@ -960,9 +971,14 @@

    Creation

  • - An Anonymous TD MUST be submitted to the directory using an HTTP `POST` request - at `/things` endpoint. + An Anonymous TD MUST be submitted to the directory in the body of + an HTTP `POST` request at `/things` endpoint. + + The request SHOULD contain `application/td+json` Content-Type header for + JSON serialization of TD. + + The TD object is validated in accordance with [[[#validation]]]. Upon successful processing, the server MUST respond with 201 (Created) status and a Location header containing a system-generated identifier for the TD. @@ -1003,7 +1019,7 @@

    Creation

    Retrieval

    - The API MUST allow retrieval of an existing TD using an HTTP `GET` request + The retrieval of an existing TD MUST be done using an HTTP `GET` request at `/things/{id}` endpoint, where `id` is the unique TD identifier. @@ -1129,9 +1145,9 @@

    Retrieval

    Update

    - - The API MUST allow modifications to an existing TD as full replacement or partial updates. - + The update operations are to replace or partially modify an existing TD. +

    +

    The update operations are described below:

    @@ -1249,7 +1265,7 @@

    Update

    Deletion

    - A TD MUST be removed from the directory when an HTTP `DELETE` request is submitted + A delete operation MUST be done using an HTTP `DELETE` request is submitted at `/things/{id}`, where `id` is the identifier of the existing TD. @@ -1550,7 +1566,7 @@

    Validation

    -

    Management

    +

    Management API

    To do: Other administrative functions not having to do with CRUD of individual records, for example, security configuration. @@ -1559,7 +1575,7 @@

    Management

    -

    Notification

    +

    Events API

    The Notification API is to notify clients about the changes to TDs maintained within the directory. @@ -1762,7 +1778,7 @@

    Notification

    • +
  • + + The API MAY provide the interfaces to + create, read, update, and delete (CRUD) TDs. +
  • Fully fledged HTTP directories SHOULD implement all of CRUDL (create, read, update, delete, and list) interfaces. - It is practical to only implement interfaces to list and retrieve + It is practical to implement only the interfaces to read and list if the directory serves a static collection of TDs. - This is also useful for directories that only intend to expose - read operations over HTTP, and perform other interactions via non-HTTP protocols. + This is also useful for directories that intend to expose only + retrieval operations over HTTP, and perform other interactions via non-HTTP protocols. To expose read-only access, the directory MUST enforce access control From f1234b53aa61846c2e0d68c2a081c471a2b89d81 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 14 Feb 2022 11:51:37 +0100 Subject: [PATCH 07/17] Explain status codes for missing features --- index.html | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 32717aba..f4748d1d 100644 --- a/index.html +++ b/index.html @@ -876,6 +876,33 @@

    Directory Service API

    incremental transfer of the payloads.

    +

    + The directory APIs include mandatory, recommended, and optional + features. + Directories that don't offer recommended or optional features + inform the clients about the absence of those features + according to the following rules: +

      +
    • + If the missing feature is to customize existing functionality of an + API, the server will respond with 501 (Not Implemented) + HTTP status. For example, if a client requests a list of + items with a particular sorting order, the server either + respects that request and returns the list with the requested + order, or rejects the request and does not return the list. + The server will return the list with the default order + if and only if custom sorting is not requested. +
      • +
    • + If the missing feature is the whole functionality at an API endpoint, + the server may respond with 404 (Not Found). + Alternatively, a server may respond with 501 (Not Implemented) + to signify that it has placeholders in place for the given + endpoint and would provide this functionality in future. +
      • +
    +

    +

    Things API

    @@ -1899,7 +1926,6 @@

    Semantic search: SPARQL

  • 400 (Bad Request): SPARQL query not provided or contains syntax errors.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • -
  • 501 (Not Implemented): SPARQL API not supported.

From 86349a836f506bc76690a4f0b9de5a649dbd35e2 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 14 Feb 2022 12:20:35 +0100 Subject: [PATCH 08/17] Reference search API for filtering from list --- index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index f4748d1d..4350d01a 100644 --- a/index.html +++ b/index.html @@ -917,11 +917,13 @@

Things API

  • The API MUST provide the interface to list TDs. + The Search API allows filtering and selection from this list; see + [[[#exploration-directory-api-search]]].
  • The API MAY provide the interfaces to - create, read, update, and delete (CRUD) TDs. + create, read, update, and delete (CRUD) individual TDs.
  • From 10de6e0b981a5ccabbbfb2b74c1450378ec1045e Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 14 Feb 2022 18:13:02 +0100 Subject: [PATCH 09/17] Assertion for 404 Not Found for missing endpoint --- index.html | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 4350d01a..b03471d0 100644 --- a/index.html +++ b/index.html @@ -886,19 +886,19 @@

    Directory Service API

  • If the missing feature is to customize existing functionality of an API, the server will respond with 501 (Not Implemented) - HTTP status. For example, if a client requests a list of + HTTP status. + For example, if a client requests a list of items with a particular sorting order, the server either respects that request and returns the list with the requested order, or rejects the request and does not return the list. The server will return the list with the default order if and only if custom sorting is not requested. + The normative behavior is prescribed in the respective sections.
  • - If the missing feature is the whole functionality at an API endpoint, - the server may respond with 404 (Not Found). - Alternatively, a server may respond with 501 (Not Implemented) - to signify that it has placeholders in place for the given - endpoint and would provide this functionality in future. + + If an API endpoint is not provided, the server SHOULD respond with + 404 (Not Found).

    • @@ -1046,6 +1046,7 @@

    Creation

  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • +
  • 404 (Not Found): Endpoint not provided.

    • @@ -1076,6 +1077,7 @@

    Retrieval

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

    • @@ -1295,6 +1297,7 @@

    Update

  • 404 (Not Found): TD with the given `id` not found (for `PATCH` only).
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • +
  • 404 (Not Found): Endpoint not provided.

    • @@ -1319,6 +1322,7 @@

    Deletion

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

    • @@ -1532,6 +1536,9 @@

    Listing

    @@ -1872,6 +1879,7 @@

    Syntactic search: JSONPath

  • 400 (Bad Request): JSONPath expression not provided or contains syntax errors.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • +
  • 404 (Not Found): Endpoint not provided.

    • @@ -1894,6 +1902,7 @@

    Syntactic search: XPath

  • 400 (Bad Request): XPath expression not provided or contains syntax errors.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • +
  • 404 (Not Found): Endpoint not provided.

    • @@ -1928,6 +1937,7 @@

    Semantic search: SPARQL

  • 400 (Bad Request): SPARQL query not provided or contains syntax errors.
  • 401 (Unauthorized): No authentication.
  • 403 (Forbidden): Insufficient rights to the resource.
    • +
  • 404 (Not Found): Endpoint not provided.

    • From df1b1525ee4b12671e0905953a2de3a4f86bed84 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 14 Feb 2022 18:18:02 +0100 Subject: [PATCH 10/17] Describe the full HTTP directory --- index.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index b03471d0..8b0564b4 100644 --- a/index.html +++ b/index.html @@ -926,8 +926,10 @@

    Things API

    create, read, update, and delete (CRUD) individual TDs.
  • + A directory that provides both read and write over HTTP is considered + a full HTTP directory. - Fully fledged HTTP directories SHOULD implement all of + Full HTTP directories SHOULD implement all of CRUDL (create, read, update, delete, and list) interfaces. It is practical to implement only the interfaces to read and list @@ -956,7 +958,7 @@

    Things API

    - The CRUDL operations are described below: + The CRUDL operations are described in the following sections:

    From 479a87d8df9df6c461271b2e3a0b30c3cb86da6f Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 14 Feb 2022 18:31:34 +0100 Subject: [PATCH 11/17] Update spacing to trigger preview build --- index.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.html b/index.html index 8b0564b4..e6badc4f 100644 --- a/index.html +++ b/index.html @@ -911,6 +911,7 @@

    Things API

    create, retrieve, update, delete, and list (CRUDL) TDs. The design of this API is in accordance with [[RFC7231]] and [[?REST-IOT]].

    +

    The HTTP API follows these general rules:

      @@ -931,12 +932,10 @@

      Things API

      Full HTTP directories SHOULD implement all of CRUDL (create, read, update, delete, and list) interfaces. - It is practical to implement only the interfaces to read and list if the directory serves a static collection of TDs. This is also useful for directories that intend to expose only retrieval operations over HTTP, and perform other interactions via non-HTTP protocols. - To expose read-only access, the directory MUST enforce access control on create, update, and delete interfaces. From de1987e01b63bb96ea46a2f8bb38bcef4742d15d Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Fri, 18 Feb 2022 13:53:51 +0100 Subject: [PATCH 12/17] Revert TM note with updates --- index.html | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index e6badc4f..8aaff5b7 100644 --- a/index.html +++ b/index.html @@ -911,7 +911,7 @@

      Things API

      create, retrieve, update, delete, and list (CRUDL) TDs. The design of this API is in accordance with [[RFC7231]] and [[?REST-IOT]].

      - +

      The HTTP API follows these general rules:

        @@ -2246,6 +2246,19 @@

        Incremental Transfer

        Directory Service API Specification (Thing Model)

        +

        + To do: add a + Thing Model + (`directory.tm.json`) + that can derive to + this TD + as an example. + The TM should describe all interaction affordances and indicate which ones + are required (i.e. mandatory by this spec). Moreover, it should use placeholders + for deployment-specific attributes. + Informative affordances (JSONPath and XPath) should be defined as such. +

        + The API of the directory is specified as a Thing Model. The Thing Model alone should not be considered as the reference to implement or interact with a directory. From ce069e52327b3185c2a9604cbc8d1be71270f89f Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 21 Feb 2022 15:48:05 +0100 Subject: [PATCH 13/17] Change from non-http to out-of-band --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 8aaff5b7..a8971752 100644 --- a/index.html +++ b/index.html @@ -935,7 +935,7 @@

        Things API

        It is practical to implement only the interfaces to read and list if the directory serves a static collection of TDs. This is also useful for directories that intend to expose only - retrieval operations over HTTP, and perform other interactions via non-HTTP protocols. + retrieval operations over HTTP, and perform other interactions via out-of-band mechanisms. To expose read-only access, the directory MUST enforce access control on create, update, and delete interfaces. From 83557fece07bced13d3ca38d847d63e73dc01655 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 21 Feb 2022 15:50:26 +0100 Subject: [PATCH 14/17] Fix delete assertion text --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index a8971752..483dc931 100644 --- a/index.html +++ b/index.html @@ -1307,7 +1307,7 @@

        Update

        Deletion

        - A delete operation MUST be done using an HTTP `DELETE` request is submitted + A delete operation MUST be done using an HTTP `DELETE` request at `/things/{id}`, where `id` is the identifier of the existing TD. From cc78d7355ffc386e607c5064c859698ea0afb517 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 21 Feb 2022 15:52:18 +0100 Subject: [PATCH 15/17] Fix 400 status text --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 483dc931..fe163738 100644 --- a/index.html +++ b/index.html @@ -1042,7 +1042,7 @@

        Creation

        • 400 (Bad Request): Bad user input such as - invalid serialization, invalid TD, `id` mismatch. + invalid serialization, invalid TD, or `id` mismatch. This is accompanied by an appropriate response message.
        • 401 (Unauthorized): No authentication.
          • From 875ea483ca6a271f9f674ec156226fb8af91a3cc Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 21 Feb 2022 16:13:23 +0100 Subject: [PATCH 16/17] Remove Management API section --- index.html | 9 --------- 1 file changed, 9 deletions(-) diff --git a/index.html b/index.html index fe163738..ccbe871b 100644 --- a/index.html +++ b/index.html @@ -1611,15 +1611,6 @@

          Validation

    -
    -

    Management API

    -

    - To do: 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). -

    -

    Events API

    From f5851b1cf9abc9903c8af36de961b31fabf4c74d Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Mon, 21 Feb 2022 16:25:13 +0100 Subject: [PATCH 17/17] Fix out-of-band text --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index ccbe871b..487fdc5b 100644 --- a/index.html +++ b/index.html @@ -935,7 +935,7 @@

    Things API

    It is practical to implement only the interfaces to read and list if the directory serves a static collection of TDs. This is also useful for directories that intend to expose only - retrieval operations over HTTP, and perform other interactions via out-of-band mechanisms. + retrieval operations over HTTP, and perform other operations via out-of-band mechanisms. To expose read-only access, the directory MUST enforce access control on create, update, and delete interfaces.