From 4383f052ac12bddb52e5884cf7bf117f4f63c9df Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Wed, 23 Mar 2016 10:57:34 -0600 Subject: [PATCH 01/14] remove .ttl from RDFSource URIs --- content-representation.md | 2 +- recommendations-server.md | 2 +- solid-webid-profiles.md | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content-representation.md b/content-representation.md index f91d861..dbde18c 100644 --- a/content-representation.md +++ b/content-representation.md @@ -42,7 +42,7 @@ Our motivation is threefold: even though the resource is stored as a Turtle file). 3. Direct mapping: the URLs map directly to the file system resources -- i.e. - `https://example.org/test.ttl` maps to `/home/user/www/test.ttl` + `https://example.org/avatar.png` maps to `/home/user/www/avatar.png` Servers must support the HEAD method for reading data. This returns a list of headers related to the resource in question. Among these headers, two very diff --git a/recommendations-server.md b/recommendations-server.md index 6ef8870..13df015 100644 --- a/recommendations-server.md +++ b/recommendations-server.md @@ -49,7 +49,7 @@ space#preferencesFile](http://www.w3.org/ns/pim/space#preferencesFile) property. ```ttl <#me> - <../settings/preferences.ttl> ; + <../settings/preferences> ; ``` ##### `/inbox/` (Inbox) diff --git a/solid-webid-profiles.md b/solid-webid-profiles.md index 23802d5..bb51e71 100644 --- a/solid-webid-profiles.md +++ b/solid-webid-profiles.md @@ -140,7 +140,7 @@ across several RDF documents: * `/profile/card` - their primary (public-readable) WebID Profile. Which would contain a `space:preferencesFile` link to: -* `/settings/prefs.ttl` - a private (only the user has read/write access) +* `/settings/preferences` - a private (only the user has read/write access) Preferences file which contains further profile-related statements. ### Extended Profile @@ -247,16 +247,16 @@ For example, a link to the Listed Type Index in the main profile document: <#me> a foaf:Person ; - . + . ``` And an example corresponding link to the Unlisted Type Index, in a private resources of the Extended Profile, such as the Preferences file -(in `/settings/prefs.ttl`): +(in `/settings/preferences`): ```ttl # ... <#me> - . + . ``` From 5a2998553fd61037063e3e4d57fcf772c324205e Mon Sep 17 00:00:00 2001 From: Alan Jenkins Date: Thu, 15 Nov 2018 19:44:43 +0000 Subject: [PATCH 02/14] recommendations-server: better example domains We need more than one example domain. `.example` TLD is defined for this purpose. Let's use it. https://tools.ietf.org/html/rfc2606 - "Reserved Top Level DNS Names". Also add missing quotes around one URI. We do not want these URIs to be clickable. --- recommendations-server.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/recommendations-server.md b/recommendations-server.md index 91b50f8..6b408b5 100644 --- a/recommendations-server.md +++ b/recommendations-server.md @@ -75,29 +75,29 @@ clients). **1)** When the `Origin` header is set: -1. Client (browser) loads an app from `https://app.org` and wants to send an XHR - (ajax) request to the server at `https://example.org`. Before sending the +1. Client (browser) loads an app from `https://app.example` and wants to send an XHR + (ajax) request to the server at `https://server.example`. Before sending the request over the wire, the browser adds the `Origin` header: `Origin: - https://app.org`, which corresponds to the domain from where the app was loaded. + https://app.example`, which corresponds to the domain from where the app was loaded. -2. The server running on https://example.org receives the request and looks at the - `Origin` header. It sees `https://app.org`, stores the value and handles the +2. The server running on `https://server.example` receives the request and looks at the + `Origin` header. It sees `https://app.example`, stores the value and handles the request. 3. The server responds to the request and sets the value of the request `Origin` header to the CORS header in the HTTP response: ```http -Access-Control-Allow-Origin: https://app.org +Access-Control-Allow-Origin: https://app.example ``` **2)** Without an `Origin` header: -1. A curl request is sent from the terminal to `https://example.org`. Unless +1. A curl request is sent from the terminal to `https://server.example`. Unless explicitly specified though a curl parameter, the `Origin` header will not be set. -2. The server running on `https://example.org` receives the request and does not +2. The server running on `https://server.example` receives the request and does not find an `Origin` header. 3. The server responds to the request and sets a default "all" value for the From 85371d21424c2d80fc4d53a9da201bba8de3504e Mon Sep 17 00:00:00 2001 From: Sebastien Dubois Date: Tue, 30 Apr 2019 16:11:16 +0200 Subject: [PATCH 03/14] Fixed a typo --- api-websockets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index ec046f6..cbead7e 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -8,7 +8,7 @@ versioned as a whole. Live updates are currently only supported through WebSockets. This describes a subscription mechanism through which clients can be notified in real time of -changes affecting a give resource. +changes affecting a given resource. The PubSub system is very basic. Clients only need to open a WebSocket connection and *sub*(scribe) to a given resource URI. If any change occurs in @@ -16,7 +16,7 @@ that resource, a *pub*(lish) event will be sent to all the subscribed clients. The WebSocket server URI is the same for any resource located on a given data space (same hostname). To discover the URI of the WebSocket server, clients can -send an HTTP OPTIONS. The server will then include an `Updates-Via` header in +send an HTTP OPTIONS request. The server will then include an `Updates-Via` header in the response: REQUEST: From ae29bbe874342dac532aaa1f4aac83fc30f15d09 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 28 May 2019 11:22:25 +0200 Subject: [PATCH 04/14] Clarify container deletion, fix #172 --- api-rest.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/api-rest.md b/api-rest.md index b7f0805..93c8b6d 100644 --- a/api-rest.md +++ b/api-rest.md @@ -58,6 +58,9 @@ HTTP/1.1 200 OK "780" . ``` +### Deleting containers +A container can only be deleted if contains neither member resources nor ACL documents. + #### Globbing (inlining on GET) **Note: this feature is _at risk_ of being From daec2fac2cc22b8dc66b4c7b4db72c085e012381 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 28 May 2019 11:23:17 +0200 Subject: [PATCH 05/14] Fix title style --- api-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-rest.md b/api-rest.md index 93c8b6d..8f77335 100644 --- a/api-rest.md +++ b/api-rest.md @@ -58,7 +58,7 @@ HTTP/1.1 200 OK "780" . ``` -### Deleting containers +#### Deleting containers A container can only be deleted if contains neither member resources nor ACL documents. #### Globbing (inlining on GET) From 8eca544381a81c6617ddf1095c3ce7f33b80a99f Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 28 May 2019 11:32:45 +0200 Subject: [PATCH 06/14] move deleting containers section under creating containers --- api-rest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-rest.md b/api-rest.md index 8f77335..dd55d10 100644 --- a/api-rest.md +++ b/api-rest.md @@ -58,9 +58,6 @@ HTTP/1.1 200 OK "780" . ``` -#### Deleting containers -A container can only be deleted if contains neither member resources nor ACL documents. - #### Globbing (inlining on GET) **Note: this feature is _at risk_ of being @@ -238,6 +235,9 @@ RESPONSE: HTTP/1.1 201 Created ``` +### Deleting containers +A container can only be deleted if contains neither member resources nor ACL documents. + ### Creating documents (files) To create a new resource, the `Link` header value must be set to the following From 34d2fc2090f1aea0737d1513d15be6d07f91aa5b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 28 May 2019 11:38:35 +0200 Subject: [PATCH 07/14] document WAC-Allow headers fixes https://github.com/solid/web-access-control-spec/issues/43 --- api-rest.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/api-rest.md b/api-rest.md index b7f0805..41b266e 100644 --- a/api-rest.md +++ b/api-rest.md @@ -382,3 +382,11 @@ Access-Control-Allow-Origin: * Access-Control-Expose-Headers: User, Triples, Location, Link, Vary, Last-Modified, Content-Length Allow: OPTIONS, HEAD, GET, PATCH, POST, PUT, DELETE ``` + +### WAC-Allow headers +Servers SHOULD send a WAC-Allow response header on HEAD and GET, with a value like: + +```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 From 3c59b842e0fd89946de3b55032dd1268ed62d763 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Wed, 29 May 2019 09:06:46 +0200 Subject: [PATCH 08/14] mention read caps in Updates-Via --- api-websockets.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index cbead7e..56381c6 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -31,9 +31,10 @@ RESPONSE: ```http HTTP/1.1 200 OK ... -Updates-Via: wss://example.org/ +Updates-Via: wss://example.org/?access_token=Ne3jiZ1Mei6Air6iefoh ``` +The URL mentioned in the `Updates-Via` header should act as a [capability](https://en.wikipedia.org/wiki/Capability-based_security). To subscribe to a resource, clients will need to send the keyword `sub` followed by an empty space and then the URI of the resource: @@ -41,7 +42,7 @@ by an empty space and then the URI of the resource: sub https://example.org/data/test ``` -If a change occurs and the client is subscribed to that resource, it will +If a change occurs and the client is subscribed to that resource and has Read access to it, it will receive a WebSocket message composed of the keyword `pub`, followed by an empty space and the URI of the resource that has changed: @@ -50,9 +51,10 @@ pub https://example.org/data/test ``` Subscribing to a container can also be really useful, since all CRUD operations -(POST, PUT, PATCH, DELETE) performed on resources of that container will trigger +(POST, PUT, PATCH, DELETE) performed on member resources of that container will trigger a notification for the container URI. This makes synchronization between -multiple apps really easy. +multiple apps really easy. It only affects the parent container, of which the resource is a member, +not further ancestor containers. For example, a client subscribes to the `data/` container: @@ -75,6 +77,10 @@ Then the following notification message will be sent: pub https://example.org/data/ ``` +The server may send additional informational messages for e.g. error reporting, +as long as they don't start with `pub`. +If a client subscribes to too many updates, the server may close the socket. + Here is a Javascript example on how to subscribe to live updates for a `test` resource at `https://example.org/data/test`: From f0cd5e88830ccb3fecf5492c7a018f42a0b305fe Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Wed, 29 May 2019 09:08:33 +0200 Subject: [PATCH 09/14] Revert accidental commit to master branch --- api-websockets.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index 56381c6..cbead7e 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -31,10 +31,9 @@ RESPONSE: ```http HTTP/1.1 200 OK ... -Updates-Via: wss://example.org/?access_token=Ne3jiZ1Mei6Air6iefoh +Updates-Via: wss://example.org/ ``` -The URL mentioned in the `Updates-Via` header should act as a [capability](https://en.wikipedia.org/wiki/Capability-based_security). To subscribe to a resource, clients will need to send the keyword `sub` followed by an empty space and then the URI of the resource: @@ -42,7 +41,7 @@ by an empty space and then the URI of the resource: sub https://example.org/data/test ``` -If a change occurs and the client is subscribed to that resource and has Read access to it, it will +If a change occurs and the client is subscribed to that resource, it will receive a WebSocket message composed of the keyword `pub`, followed by an empty space and the URI of the resource that has changed: @@ -51,10 +50,9 @@ pub https://example.org/data/test ``` Subscribing to a container can also be really useful, since all CRUD operations -(POST, PUT, PATCH, DELETE) performed on member resources of that container will trigger +(POST, PUT, PATCH, DELETE) performed on resources of that container will trigger a notification for the container URI. This makes synchronization between -multiple apps really easy. It only affects the parent container, of which the resource is a member, -not further ancestor containers. +multiple apps really easy. For example, a client subscribes to the `data/` container: @@ -77,10 +75,6 @@ Then the following notification message will be sent: pub https://example.org/data/ ``` -The server may send additional informational messages for e.g. error reporting, -as long as they don't start with `pub`. -If a client subscribes to too many updates, the server may close the socket. - Here is a Javascript example on how to subscribe to live updates for a `test` resource at `https://example.org/data/test`: From 9fad16a7c4c30cdbc785d3dc0bb5721f1c7e842f Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Wed, 29 May 2019 09:46:51 +0200 Subject: [PATCH 10/14] mention relative URLs --- api-websockets.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/api-websockets.md b/api-websockets.md index cbead7e..efb9326 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -49,6 +49,9 @@ space and the URI of the resource that has changed: pub https://example.org/data/test ``` +Some implementations also support using IRIs that are relative to the host, +e.g. `/data/test` instead of `https://example.org/data/test`. + Subscribing to a container can also be really useful, since all CRUD operations (POST, PUT, PATCH, DELETE) performed on resources of that container will trigger a notification for the container URI. This makes synchronization between From d025e423e36f9ccd736ddac4b3bd0dae1fb04b96 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 30 May 2019 09:42:32 +0200 Subject: [PATCH 11/14] fix confusing remark about NSS divergence from the spec --- api-websockets.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-websockets.md b/api-websockets.md index efb9326..5e92d27 100644 --- a/api-websockets.md +++ b/api-websockets.md @@ -49,8 +49,7 @@ space and the URI of the resource that has changed: pub https://example.org/data/test ``` -Some implementations also support using IRIs that are relative to the host, -e.g. `/data/test` instead of `https://example.org/data/test`. +Only absolute URIs should be used in both the `sub` and the `pub` message. Subscribing to a container can also be really useful, since all CRUD operations (POST, PUT, PATCH, DELETE) performed on resources of that container will trigger From fe586673278f6adc6a08c7da6ed94cb3116c787b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 30 May 2019 14:21:19 +0200 Subject: [PATCH 12/14] typo --- api-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-rest.md b/api-rest.md index dd55d10..6191e2d 100644 --- a/api-rest.md +++ b/api-rest.md @@ -236,7 +236,7 @@ HTTP/1.1 201 Created ``` ### Deleting containers -A container can only be deleted if contains neither member resources nor ACL documents. +A container can only be deleted if it contains neither member resources nor ACL documents. ### Creating documents (files) From b8924ceec9504063a97078da594ffc4fcf8c0cd1 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 17 Jun 2019 12:16:23 +0200 Subject: [PATCH 13/14] Fix review comments --- api-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-rest.md b/api-rest.md index 6191e2d..b2b0cef 100644 --- a/api-rest.md +++ b/api-rest.md @@ -236,7 +236,7 @@ HTTP/1.1 201 Created ``` ### Deleting containers -A container can only be deleted if it contains neither member resources nor ACL documents. +A container can only be deleted if it contains no resources. ### Creating documents (files) From 1db9b1c7a5fdbb963591e30d79a965f124f19217 Mon Sep 17 00:00:00 2001 From: A_A <21040751+Otto-AA@users.noreply.github.com> Date: Mon, 1 Jul 2019 17:22:02 +0200 Subject: [PATCH 14/14] Change ambiguous PUT description in api-rest.md From my point of view, the word `standard` could be interpreted as "usual/common" but also as "specification-standard" (see #198 ). Therefore I'd propose to change it to the word "common". --- api-rest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-rest.md b/api-rest.md index 03f7166..e32502e 100644 --- a/api-rest.md +++ b/api-rest.md @@ -271,7 +271,7 @@ More examples can be found in the LDP [Primer document](http://www.w3.org/TR/ldp #### HTTP PUT to create -An alternative (though not standard) way of creating new resources is to use +An alternative (though not common) way of creating new resources is to use HTTP PUT. Although HTTP PUT is commonly used to overwrite resources, this way is usually preferred when creating new non-RDF resources (i.e. using a mime type different than `text/turtle`). @@ -392,4 +392,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.