From 35474c195f64652aa67749906bb0d8e83d99bb1b Mon Sep 17 00:00:00 2001
From: Ruben Verborgh <ruben@verborgh.org>
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 | 67 ++++++++++++++++-------------------------------------
 1 file changed, 20 insertions(+), 47 deletions(-)

diff --git a/api-rest.md b/api-rest.md
index ef9bfc6..941f7af 100644
--- a/api-rest.md
+++ b/api-rest.md
@@ -58,80 +58,53 @@ HTTP/1.1 200 OK
     <http://www.w3.org/ns/posix/stat#size> "780" .
 ```
 
-#### Globbing (inlining on GET)
+#### Globbing (concatenate RDF files in a container on GET)
 
-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.
+To optimize certain applications,
+you can aggregate all RDF resources within a container
+and retrieve them with a single `GET` operation.
+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)).
+Performing a `GET` on a URL ending in `/*`
+will return an aggregate view of all RDF resources of the corresponding container.
 
-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 example, consider a container `/data` that contains the following files:
+- `file1.ttl`
+- `file2.ttl`
+- `res3.txt`
 
-For *res1*:
+Let's assume that `/data/file1.ttl` and `/data/file2.ttl`
+contain one triple each:
 
 ```ttl
 <> a <https://example.org/ns/type#One> .
 ```
 
-For *res2*:
-
 ```ttl
 <> a <https://example.org/ns/type#Two> .
 ```
 
-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
-<res1>
-    a <https://example.org/ns/type#One> .
-
-<res2>
-    a <https://example.org/ns/type#Two> .
-```
-
-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 the union of the datasets in `file1.ttl` and `file2.ttl`:
 
 ```http
 GET /data/* HTTP/1.1
 Host: example.org
 ```
 
-RESPONSE:
-
 ```http
 HTTP/1.1 200 OK
 ```
 ```ttl
 <>
     a <http://www.w3.org/ns/ldp#BasicContainer> ;
-    <http://www.w3.org/ns/ldp#contains> <res1>, <res2> .
+    <http://www.w3.org/ns/ldp#contains> <file1.ttl>, <file2.ttl> .
 
-<res1>
+<file1.ttl>
     a <https://example.org/ns/type#One> .
 
-<res2>
+<file2.ttl>
     a <https://example.org/ns/type#Two> .
 ```