Skip to content

Commit

Permalink
Listing with chunked transfer (#145)
Browse files Browse the repository at this point in the history 
* listing with chunked transfer

* grammar fix: add article before body

* Add assertion for listing using HTTP/2 frames

As discussed, I am merging this, but Farshid will create a new PR that re-introduces header-based pagination as in PR#130.  I will close PR#130 without merging but only due to merge conflicts, which Farshid will resolve.
  • Loading branch information
@farshidtz
farshidtz authored Mar 29, 2021
1 parent 57f0155 commit e3ca84b
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 105 deletions.
15 changes: 15 additions & 0 deletions directory.td.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,21 @@
}
]
},
"retrieveTDs": {
"description": "Retrieve all Thing Descriptions",
"forms": [
{
"href": "/td",
"htv:methodName": "GET",
"response": {
"description": "Success response",
"htv:statusCodeValue": 200,
"contentType": "application/ld+json",
},
"scopes": "readAll"
}
]
},
"searchJSONPath": {
"description": "JSONPath syntactic search",
"uriVariables": {
Expand Down
141 changes: 36 additions & 105 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -985,93 +985,49 @@ <h4>Deletion</h4>
<section id="exploration-directory-api-registration-listing" class="normative">
<h4>Listing</h4>
<p>
<span class="rfc2119-assertion" id="tdd-reg-list">
The listing endpoint provides a way to query the collection of TD objects
from the directory. The Search API may be used to retrieve <a>Partial TD</a>s
or TD fragments; see [[[#exploration-directory-api-search]]].
</p>


<p>
<span class="rfc2119-assertion" id="tdd-reg-list-method">
The list of TDs MUST be retrieved from the directory using an
HTTP `GET` request to the root endpoint of the registration API.
HTTP `GET` request.
</span>

<span class="rfc2119-assertion" id="tdd-reg-list-resp">
A successful response MUST have 200 (OK) status, contain `application/ld+json`
Content-Type header, and an array of TDs in the body.
</span>
</p>
<p> <!-- paginated listing -->
<span class="rfc2119-assertion" id="tdd-reg-list-resp-pagination">
The default response MUST be paginated to limit the
set of enclosed TDs in a single response.

<p>
Serializing and returning the full list of TDs may be burdensome to servers.
As such, servers should serialize incrementally and utilize protocol-specific
mechanisms to respond in chunks.
<span class="rfc2119-assertion" id="tdd-reg-list-http11">
HTTP/1.1 servers SHOULD perform chunked
<a href="https://tools.ietf.org/html/rfc7230#section-3.3.1">Transfer-Encoding</a> [[RFC7230]]
to respond the data incrementally.
</span>
Most HTTP/1.1 clients automatically process the data received with
chunked transfer encoding.
Memory-constrained applications which require the full list
should consider processing the received data incrementally.

Chunked transfer encoding is not supported in HTTP/2.
<span class="rfc2119-assertion" id="tdd-reg-list-http2">
HTTP/2 servers SHOULD respond the data incrementally using
<a href="https://tools.ietf.org/html/rfc7540#section-4">HTTP Frames</a> [[RFC7540]].
</span>
The pagination must be based on the following rules:
<ul>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-resp">
A successful response MUST have 200 (OK) status, contain `application/ld+json`
Content-Type header, and a set of TDs in a collection object in body.
</span>
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-envelop">
The TDs MUST be complete TD objects inside an array
called `items` enclosed in the collection object.
</span>
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-total">
The number of TDs in each response MUST match the requested number.
</span>
The server should enforce an appropriate or configurable maximum number
of TDs per request to manage the processing load on the server side.
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-total-default">
When a total number is not given in a request, it MUST default to 1.
</span>
This is to avoid unintended traffic and load on memory-constrained clients.
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-id">
The collection object MUST contains an `id` attribute
pointing to the current page (self link).
</span>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-links">
The collection object MUST contains a `nextLink` attribute
for querying the next page, when present.
</span>
The links may be relative to directory API base URL, or be absolute URLs.
These links may include additional arguments for ordering or session keys.
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-total">
When requested, the collection object MUST contain a `total` attribute
equal to total number of TDs within the directory.
</span>
</li>
<li>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-order-default">
By default, the collection MUST be sorted alphanumerically
by the unique identifiers of TDs.
</span>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-order">
The server MAY support sorting by other TD attributes (e.g. `created` field) and
different sorting orders (i.e. ascendingly/descendingly).
</span>
<span class="rfc2119-assertion" id="tdd-reg-list-pagination-order-unsupported">
If the server does not support a given sorting argument,
it MUST reject the request with 501 (Not Implemented) status.
</span>
</li>
</ul>
</p>

<!-- <p>
The paginated list operation is specified as `listTD` property in
<p>
The paginated list operation is specified as `retrieveTDs` property in
[[[#directory-thing-description]]].
</p> -->
<p class="ednote" title="Registration listing query arguments">
Need to specify and describe the query arguments to paginate
and get total. The paginated list operation should be specified as `listTD`
property in [[[#directory-thing-description]]].
</p>


<span class="rfc2119-assertion" id="tdd-reg-list-resp-alternative">
A server which supports alternative mechanisms (such as streaming)
MAY rely on server-driven content negotiation and respond accordingly.
</span>

<p>
Error responses:
Expand All @@ -1085,32 +1041,7 @@ <h4>Listing</h4>
</ul>
</p>

The following is an example paginated list response with total:
<aside class="example" id="example-td-registration-info" title="Example response for a paginated list with total">
<pre>
{
"@context": "https://w3c.github.io/wot-discovery/context/discovery-context.jsonld",
"id": "/td?offset=0&limit=10",
"type": "Collection",
"items": [
{
"@context": "https://www.w3.org/2019/wot/td/v1",
"id": "urn:example:simple-td",
"title": "Simple TD",
"security": "basic_sc",
"securityDefinitions": {
"basic_sc": {
"scheme": "basic"
}
}
},
...
],
"total": 350,
"nextLink": "/td?offset=10&limit=10"
}
</pre>
</aside>

</section>

<section id="validation" class="normative">
Expand Down

0 comments on commit e3ca84b

Please sign in to comment.