Skip to content
This repository was archived by the owner on Apr 13, 2022. It is now read-only.

Clarify and detail the definition of globbing to only apply to folders #148

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Clarify and detail the definition of globbing to only apply to folders #148

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 39 additions & 52 deletions api-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,91 +58,78 @@ HTTP/1.1 200 OK
<http://www.w3.org/ns/posix/stat#size> "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)
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 <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 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 <http://www.w3.org/ns/ldp#BasicContainer> ;
<http://www.w3.org/ns/ldp#contains> <res1>, <res2> .
<http://www.w3.org/ns/ldp#contains> <resource1.ttl>, <resource2.ttl> .

<res1>
<resource1.ttl>
a <https://example.org/ns/type#One> .

<res2>
<resource2.ttl>
a <https://example.org/ns/type#Two> .
```

Note: the aggregation process is not currently recursive, therefore it will not
apply to children containers.

### Alternative: using SPARQL

Expand Down Expand Up @@ -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.
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.