From 0dfc01065246ef65074cfc6a22130418ed553b3c Mon Sep 17 00:00:00 2001 From: Ruben Verborgh Date: Tue, 26 Mar 2019 22:11:19 +0100 Subject: [PATCH] Restrict globbing to /* Closes https://github.com/solid/solid-spec/issues/147. --- api-rest.md | 91 +++++++++++++++++++++++------------------------------ 1 file changed, 39 insertions(+), 52 deletions(-) diff --git a/api-rest.md b/api-rest.md index 03f7166..a10aab0 100644 --- a/api-rest.md +++ b/api-rest.md @@ -58,7 +58,7 @@ HTTP/1.1 200 OK "780" . ``` -#### Globbing (inlining on GET) +#### Globbing (`GET` the merged RDF graph of a container) **Note: this feature is _at risk_ of being [changed](https://github.com/solid/solid-spec/pull/148) @@ -66,83 +66,70 @@ or [removed](https://github.com/solid/solid-spec/pull/151). Please join the discussion. Code depending on this will still work for now.** -We have found that in some cases, using the existing LDP features was not -enough. For instance, to optimize certain applications we needed to aggregate -all RDF resources from a container and retrieve them with a single GET -operation. We implemented this feature on the servers and decided to call it -"globbing". Similar to [UNIX shell -glob](https://en.wikipedia.org/wiki/Glob_(programming)), doing a GET on any URI -which ends with a `*` will return an aggregate view of all the resources that -match the indicated pattern. - -For example, let's assume that `/data/res1` and `/data/res2` are two resources -containing one triple each, which defines their type as follows: - -For *res1*: +To optimize certain applications, +this specification defines a single `GET` operation +that provides access to an aggregation of the RDF resources in a container. +We refer to this feature as _globbing_, +since it provides a subset of the functionality +offered by the [UNIX shell glob](https://en.wikipedia.org/wiki/Glob_(programming)). +Consider a container to which the user has _Read_ access, +which will have a URL ending in `/`. +If we append a `*` to that URL (so it ends in `/*`), +we obtain the URL of a resource that, +in response to a `GET` request, +returns the [RDF graph merge](https://www.w3.org/TR/rdf-mt/#graphdefs) +of all of the container's direct child resources +that are available in an RDF format +and for which the user has _Read_ access. +Resources with syntax errors can be ignored or be partially included, +but they do not cause a failure. +The response can contain additional metadata about the container, +such as the list of resources. + +For example, consider a container `/data` that contains the following resources: +- `resource1.ttl` +- `resource2.ttl` +- `hidden3.ttl` +- `resource4.txt` + +The user performing the request had read access to `/data`, +`resource1.ttl` and `resource2.ttl`, +but not to `hidden3.ttl`. +Let's assume that `/data/resource1.ttl` and `/data/resource2.ttl` +contain one triple each: ```ttl <> a . ``` -For *res2*: - ```ttl <> a . ``` -If one would like to fetch all resources of a container beginning with `res` -(e.g. `/data/res1`, `/data/res2`) in one request, they could do a GET on -`/data/res*` as follows. - -REQUEST: - -```http -GET /data/res* HTTP/1.1 -Host: example.org -``` - -RESPONSE: - -```http -HTTP/1.1 200 OK -``` -```ttl - - a . - - - a . -``` - -Alternatively, one could ask the server to inline *all* resources of a -container, which includes the triples corresponding to the container itself: - -REQUEST: +Then a request to `/data/*` +will return a serialization of the [RDF graph merge](https://www.w3.org/TR/rdf-mt/#graphdefs) +of the datasets contained in `resource1.ttl` and `resource2.ttl`: ```http GET /data/* HTTP/1.1 Host: example.org ``` -RESPONSE: - ```http HTTP/1.1 200 OK ``` ```ttl <> a ; - , . + , . - + a . - + a . ``` -Note: the aggregation process is not currently recursive, therefore it will not -apply to children containers. ### Alternative: using SPARQL @@ -392,4 +379,4 @@ Servers SHOULD send a WAC-Allow response header on HEAD and GET, with a value li ```http WAC-Allow: user="read write append control",public="read" ``` -In general, the format is `user="` + user-permissions = `",public="` + public-permissions + `"`. User-permissions and public-permissions should both be space-separated lists, containing a subset of ['read', 'write', 'append', 'control']. If 'write' is present then 'append' should also be present. \ No newline at end of file +In general, the format is `user="` + user-permissions = `",public="` + public-permissions + `"`. User-permissions and public-permissions should both be space-separated lists, containing a subset of ['read', 'write', 'append', 'control']. If 'write' is present then 'append' should also be present.