--- a/ldp-primer/bug_update_req.txt Mon Apr 28 14:40:40 2014 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-PUT /app/product1/bug3 HTTP/1.1
-Host: example.org
-Content-Type: text/turtle
-If-Match: W/"123456789"
-
- </app/product1/bug3> a bt:Bug;
- dcterms:title "Product 1 crashes when shutting down.";
- dcterms:creator </app/users/johndoe>;
- dcterms:created "2013-05-05T10:00"^^xsd:dateTime;
- bt:isInState "InProgress";
- bt:relatedBug </app/product1/bug4> .
-
----
-PUT /app/product1/bug3 HTTP/1.1
-Host: example.org
-Content-Type: application/ld+json
-If-Match: W/"123456789"
-
-{
- "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
- "@id": "/app/product1/bug67",
- "dcterms:title": "Product A crashes when shutting down.",
- "dcterms:creator": { "@id": "http://njh.me/app/users/johndoe" },
- "dcterms:created": {
- "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
- "@value": "2013-05-05T10:00:00"
- },
- "bt:isInState": "InProgress" ,
- "bt:relatedBug": { "@id": "/app/product1/bug4" }
-}
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ldp-primer/create_cr_req.txt Mon Apr 28 14:47:17 2014 -0400
@@ -0,0 +1,22 @@
+POST alice/ HTTP/1.1
+Host: data.example.org
+Content-Type: text/turtle
+Slug: photos
+
+<> a ldp:Container, ldp:BasicContainer;
+ dcterms:title "Photos of Alice" ;
+ dcterms:description "This container will contain photos of Alice." .
+
+---
+POST alice/ HTTP/1.1
+Host: data.example.org
+Content-Type: application/ld+json
+Slug: photos
+
+{
+ "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
+ "@id": "",
+ "@type": [ "ldp:Container", "ldp:BasicContainer"],
+ "dcterms:title": "Photos of Alice" ,
+ "dcterms:description": "This container will contain photos of Alice."
+}
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ldp-primer/create_cr_s1.txt Mon Apr 28 14:47:17 2014 -0400
@@ -0,0 +1,13 @@
+<http://data.example.org/alice/> a ldp:Container, ldp:BasicContainer ;
+ dcterms:title "Alice’s data storage on the Web" ;
+
+ ldp:contains <http://data.example.org/alice/foaf> .
+
+---
+{
+ "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
+ "@id": "http://data.example.org/alice/",
+ "@type": [ "ldp:Container", "ldp:BasicContainer"],
+ "dcterms:title": "Alice’s data storage on the Web",
+ "ldp:contains": { "@id": "http://data.example.org/alice/foaf" }
+}
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ldp-primer/create_cr_s2.txt Mon Apr 28 14:47:17 2014 -0400
@@ -0,0 +1,15 @@
+<http://data.example.org/alice/> a ldp:Container, ldp:BasicContainer ;
+ dcterms:title "Alice’s data storage on the Web";
+ ldp:contains <http://data.example.org/alice/foaf> , <http://data.example.org/alice/photos/> .
+
+---
+{
+ "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
+ "@id": "http://data.example.org/alice/",
+ "@type": [ ldp:Container, ldp:BasicContainer ],
+ "dcterms:title": "Alice’s data storage on the Web",
+ "ldp:contains": [
+ { "@id": "http://data.example.org/alice/foaf" },
+ { "@id": "http://data.example.org/alice/photos/" }
+ ]
+}
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ldp-primer/create_cr_s3.txt Mon Apr 28 14:47:17 2014 -0400
@@ -0,0 +1,17 @@
+<http://data.example.org/alice/photos/> a ldp:Container, ldp:BasicContainer;
+ dcterms:title "Photos of Alice" ;
+ dcterms:description "This container will contain photos of Alice." .
+
+---
+
+{
+ "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
+ "@id": "/app/product2/",
+ "@type": [ "ldp:Container", "ldp:BasicContainer"],
+ "dcterms:title": "Photos of Alice",
+ "dcterms:description": "This container will contain photos of Alice."
+}
+
+
+
+
\ No newline at end of file
--- a/ldp-primer/ldp-primer.html Mon Apr 28 14:40:40 2014 -0400
+++ b/ldp-primer/ldp-primer.html Mon Apr 28 14:47:17 2014 -0400
@@ -4,7 +4,9 @@
<p> Looking at the response, Alice (Alice's LDP client) can discover that this is an LDP-Basic Container and the container allows her to POST things of both RDF types (text/turtle, application/ld+json)
and images (image/bmp and image/jpeg).</p>
</section>
<section>
<h2> Creating a RDF resource (POST an RDF resource to an LDP-BC) </h2>
<p>Alice decides to create a FOAF profile for her using the LDP-BC by POSTing her FOAF personal profile document. </p>
<pre title="A request for creating a RDF resource" class="example">
POST /alice/ HTTP/1.1
Host: data.example.org
Slug: foaf
Content-Type: text/turtle
@prefix dc: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<> a foaf:PersonalProfileDocument;
foaf:primaryTopic <#me> ;
dc:title "Alice’s FOAF file" .
<#me> a foaf:Person;
foaf:name "Alice Smith" .
</pre>
<pre title="The response for creating a RDF resource" class="example">
HTTP/1.1 201 Created
Location: /alice/foaf
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Content-Length: 0
</pre>
<p> Once the resource is created, Alice can check the container again to see whether it correctly contains the newly created resource. </p>
<pre title="A request for retrieving a basic container after the new resource is created" class="example">
GET /alice/ HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<pre title="The response of retrieving a basic container after the new resource is created" class='example'>
HTTP/1.1 200 OK
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: <http://www.w3.org/ns/ldp/BasicContainer>; rel="type"
ETag: W/"123456789"
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
<http://data.example.org/alice/> a ldp:Container, ldp:BasicContainer;
dcterms:title "Alice’s data storage on the Web" ;
ldp:contains <http://data.example.org/alice/foaf> .
</pre>
</section>
<section>
<h2> Creating a non-RDF (binary) resource (POST an image to an LDP-BC) </h2>
<p> Next, Alice wants to upload a photo of her to the document storage. She can create an image by POSTing it in the same way she created the RDF document. </p>
<pre title="A request for creating a non-RDF resource" class="example">
POST /alice/ HTTP/1.1
Host: data.example.org
Slug: avatar
Content-Type: image/png
Content- Length: nnn
### binary data ###
</pre>
<pre title="The response for creating a non-RDF resource" class="example">
HTTP/1.1 201 Created
Location: /alice/avatar
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: <http://data.example.org/alice/avatar/meta>; rel="describedby"
Content-Length: 0
</pre>
<p> The outcome of creating a non-RDF is similar to creating a RDF resource. If successful, the server will return a 201 success code with a Location header that points to the created resource. However,
in the case of binary resources the server may create an additional file to maintain the metadata about the binary file like shown in the above example. </p>
</section>
<section>
<h2> Update a RDF LDP resource (PUT on an LDP-RS) </h2>
<p> After creating the image, Alice now wants to update her FOAF profile with a link to the image. So she first retrieves her FOAF profile. </p>
<pre title="A request for retrieving a RDF resource" class="example">
GET /alice/foaf HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<pre title="The response of retrieving a RDF resource" class='example'>
HTTP/1.1 200 OK
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
ETag: W/"123454321"
@prefix dc: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<> a foaf:PersonalProfileDocument;
foaf:primaryTopic <#me> ;
dc:title "Alice’s FOAF file" .
<#me> a foaf:Person;
foaf:name "Alice Smith" .
</pre>
<p> Then she updates the document and amending the document with a link to her photo and updating the document with a PUT.</p>
<pre title="A request for updating a RDF resource" class="example">
PUT /alice/foaf HTTP/1.1
Host: data.example.org
If-Match: W/"123454321"
Content-Type: text/turtle
@prefix dc: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<> a foaf:PersonalProfileDocument;
foaf:primaryTopic <#me> ;
dc:title "Alice’s FOAF file" .
<#me> a foaf:Person;
foaf:name "Alice Smith" ;
foaf:img <http://data.example.org/alice/avatar>
</pre>
<pre title="The response for updating a RDF resource" class="example">
HTTP/1.1 204 No Content
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
ETag: W/"123454322"
</pre>
<p> If the operation is successful, the document will be updated with new information. </p>
</section>
<section>
<h2> Deleting a resource (DELETE on an LDPR) </h2>
<p>If Alice decides to delete the document, she can do that with a delete operation. </p>
<pre title="A request for deleting a RDF resource" class="example">
DELETE /alice/foaf HTTP/1.1
Host: data.example.org
If-Match: W/"123454322"
</pre>
<pre title="The response for deleting a RDF resource" class="example">
HTTP/1.1 204 No Content
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
ETag: W/"123454322"
</pre>
</section>
- <section>
<h3 id="meta-structure">Structural Manipulation (Child Container)</h3>
<p>If the bug tracker allows creating new Products in the tracker, that can done by posting a representation of a new Product to the Bug Tracker container. In this example the client includes the necessary ldp membership properties making the new Product a container for Bug resources.</p>
<p>The status of the bug tracker before creating the new product.</p>
<pre title="The state of the Bug Tracker LDPC"
class='example' data-include='product_create_s1.txt'
data-oninclude='fixCode'></pre>
<p>The client POSTs a representation of a Product to the Bug Tracker LDPC.</p>
<pre title="A request for creating a product"
class='example' data-include='product_create_req.txt'
data-oninclude='fixCode'></pre>
<p>If the create is successful, the server responds with location of the newly created resource.</p>
<pre title="The response after creating new product" class="example">
HTTP/1.1 201 Created
Location: /app/product2
Content-Length: 0
</pre>
<p>After creation of this new container, 'product2', the representation of the 'Tracker' container will be</p>
<pre title="The state of the Bug Tracker after the product creation"
class='example' data-include='product_create_s2.txt'
data-oninclude='fixCode'></pre>
<p>and the 'product2' will have the following representation.</p>
<pre title="The state of the new Product"
class='example' data-include='product_create_s3.txt'
data-oninclude='fixCode'></pre>
</section>
+ <section>
<h3 id="meta-structure">Structural Manipulation (Child Containers)</h3>
<p> To organize the documents in a better manner, the online document store allows creation of child containers. That is under the root container, Alice can create a container hierarchy to organise
+ her documents. This can be done by POSTing (a child) container representation to a (parent) container.
+ </p>
<p>So if Alice wants to create a child container so that she can keep all her images organized in a separate container. </p>
<pre title="The state of Alice's document store before creating the photo (child) container"
class='example' data-include='create_cr_s1.txt'
data-oninclude='fixCode'></pre>
<p>So Alice POSTs a representation of a container (LDP-BC) for creating photos to the root container.</p>
<pre title="A request for creating a new container"
class='example' data-include='create_cr_req.txt'
data-oninclude='fixCode'></pre>
<p>If the create is successful, the server responds with location of the newly created container for the photos.</p>
<pre title="The response after creating the new container" class="example">
HTTP/1.1 201 Created
Location: /alice/photos/
Content-Length: 0
</pre>
<p>After creation of this new container, the parent container will look like </p>
<pre title="The state of Alice's document store after creating the photo (child) container"
class='example' data-include='create_cr_s2.txt'
data-oninclude='fixCode'></pre>
<p>and the photo container will look like the following.</p>
<pre title="The state of Alice's newly created photo container"
class='example' data-include='create_cr_s3.txt'
data-oninclude='fixCode'></pre>
</section>
</section>
<section id="bugtracker">
<h1>Bug Tracker Example (LDP Direct containers)</h1>
<p> The previous section provided practical examples of basic LDP interactions. One thing to note the example
was using LDP Basic Containers. One of the limitations of LDP Basic Containers is that it only uses LDP
vocabulary. However, there are scenarios where the applications want to use their own domain specific vocabulary
for listing members of a container. For example, an application which already had its own vocabulary would like
continue using the same vocabulary when using LDP protocol. LDP Direct containers allow the domain-specific
vocabulary to be used when listing members in a container. </p>
<p> In addition to using the domain-specific vocabularies, in some applications would like to represent
relationships other than the containment relationship of information resources within the containers. One example is
that information resources contains relationship about non-information resources or real world things. LDP Indirect
Containers allows the containers use these relations when new resources are created.
</p>
<p class="note">For more information on information resources (documents) vs real world entities (things) separation please refer to <a href="http://www.w3.org/TR/webarch/#id-resources">Web Arch (Section 2.2. URI/Resource Relationships) </a>,
, <a href="http://www.w3.org/TR/cooluris/#semweb">Cool URIs (Section 3. URIs for Real-World Objects)</a>, <a href="http://www.w3.org/TR/urls-in-data/#landing-pages">URLs in Data (Section 3. Landing Pages and Records)</a>.</p>
<p>
The examples in this section will revolve around a very simple Bug Tracker application. Bug Tracker application records
the bugs of several products allowing reporting, updating and deleting bugs and products. In contrast to the online document store example, the bug tracker wants to use a simple domain vocabulary
, e.g. has_bug or related, to express membership relationships in the containers. LDP provides the additional interaction capability in the protocol to perform dynamic evolution of knowledge representation.
</p>
<p>RESTful APIs are often documented by through listing valid operations operating on URLs described as templates. A RESTful API for a simple Bug Tracker system might be described as follows:</p>
<table class="simple">
<thead>
<th>Path</th>
<th>Method</th>
<th>Description</th>
</thead>
<tbody>
<!--tr>
<td rowspan="5">/app/</td>
<td>GET</td>
<td>Lists all the product descriptions.</td>
</tr>
<tr>
<td>POST</td>
<td>Create a new product description.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the app description and/or list of product descriptions</td>
</tr>
<tr>
<td>PATCH</td>
<td>Update the app description and/or list of product descriptions</td>
</tr>
<tr>
<td>DELETE</td>
<td>Not allowed.</td>
</tr-->
<tr>
<td class="col1" rowspan="5"><div class='code'>/app/{product-id}/</div></td>
<td>GET</td>
<td>Lists the bug reports associated with a product.</td>
</tr>
<tr>
<td>POST</td>
<td>Create a new bug report associated with a product.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the project description.</td>
</tr>
<tr>
<td>PATCH</td>
<td>Not supported.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Delete the project description and associated bug reports.</td>
</tr>
<tr>
<td rowspan="5"><div class='code'>/app/{product-id}/{bug-id}</div></td>
<td>GET</td>
<td>Gets the bug report.</td>
</tr>
<tr>
<td>POST</td>
<td>Not supported.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the bug report.</td>
</tr>
<tr>
<td>PATCH</td>
<td>Not supported.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Delete the bug report.</td>
</tr>
<tr>
<td rowspan="2"><div class='code'>/*/*</div></td>
<td>OPTIONS</td>
<td>Discover the allowed operations over a resource</td>
</tr>
<tr>
<td>HEAD</td>
<td>Only retrieve metainformation about a resource</td>
</tr>
</tbody>
</table>
<section id="navandret">
<h2>Navigation and Retreival</h2>
<p> One of the main use cases of the example bug tracker is to list of the bugs of a given product. Assuming
that a user got a URL of a product by out of band means, one can look it up to get more information including
the bugs associated with it.</p>
<p>To get the description of the product, a client can do a GET request on the URI of the known product resource. LDPR
servers should provide text/turtle representations of the requested LDPRs and may provide RDF format representations
using standard HTTP content negotiation. </p>
<pre class="example" title="Product lookup request"
data-include='product_lookup_req.txt' data-oninclude='fixCode'></pre>
<p>If the product resource is available, the server responds with the representation of the resource using the requested media type,
<code>text/turtle</code> in this case.</p>
<pre title="HTTP response for product lookup" class='example' data-include='product_lookup_resp.txt' data-oninclude='fixCode'></pre>
<p>The project description resource contains both information about the project such as the title and the information about members of the product LDPC, i.e. the bugs associated with the product. This example uses an LDP Direct Container allowing the application to use domain specific vocabulary in the container. For example, it manages
the (<?productURI>, bt:hasbug, <?bugURI>) relationship using the application-specific vocabulary. The next example illustrates the behaviour of LDP Direct containers when new resources
are created. </p>
--- a/ldp-primer/product_create_req.txt Mon Apr 28 14:40:40 2014 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,28 +0,0 @@
-POST /app/ HTTP/1.1
-Host: example.org
-Content-Type: text/turtle
-Slug: product2
-
-<> a ldp:Container, bt:Product;
- ldp:membershipSubject <>;
- ldp:membershipPredicate bt:hasbug;
- ldp:membershipObject ldp:MemberSubject;
- dcterms:title "Product Two" ;
- dcterms:description "A container that tracks bugs of Product Two" .
-
----
-POST /app/ HTTP/1.1
-Host: example.org
-Content-Type: application/ld+json
-Slug: product2
-
-{
- "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
- "@id": "",
- "@type": [ "bt:Product", "ldp:Container"],
- "ldp:membershipSubject": "",
- "ldp:membershipObject": "ldp:MemberSubject",
- "ldp:membershipPredicate": "bt:hasbug",
- "dcterms:title": "Product Two" ,
- "dcterms:description": "A container that tracks bugs of Product Two"
-}
\ No newline at end of file
--- a/ldp-primer/product_create_s1.txt Mon Apr 28 14:40:40 2014 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-</app/> a ldp:Container, bt:BugTracker ;
- ldp:membershipSubject <>;
- ldp:membershipPredicate bt:tracksProject ;
- ldp:membershipObject ldp:MemberSubject;
- dcterms:title "Bug tracker application";
- bt:tracksProject </app/product1> .
-
----
-{
- "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
- "@id": "/app/",
- "@type": [ "bt:BugTracker", "ldp:Container"],
- "ldp:membershipSubject": { "@id": "" },
- "ldp:membershipPredicate": { "@id": "bt:tracksProject" },
- "ldp:membershipObject": { "@id": "ldp:MemberSubject" },
- "dcterms:title": "Bug tracker application",
- "bt:tracksProject": { "@id": "/app/product1" }
-}
\ No newline at end of file
--- a/ldp-primer/product_create_s2.txt Mon Apr 28 14:40:40 2014 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,21 +0,0 @@
-</app/> a ldp:Container, bt:BugTracker ;
- ldp:membershipSubject <>;
- ldp:membershipPredicate bt:tracksProject ;
- ldp:membershipObject ldp:MemberSubject;
- dcterms:title "Bug tracker application";
- bt:tracksProject </app/product1> , </app/product2> ;
-
----
-{
- "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
- "@id": "/app/",
- "@type": [ "bt:BugTracker", "ldp:Container"],
- "ldp:membershipSubject": { "@id": "" },
- "ldp:membershipPredicate": { "@id": "bt:tracksProject" },
- "ldp:membershipObject": { "@id": "ldp:MemberSubject" },
- "dcterms:title": "Bug tracker application",
- "bt:tracksProject": [
- { "@id": "/app/product1" },
- { "@id": "/app/product2" }
- ]
-}
\ No newline at end of file
--- a/ldp-primer/product_create_s3.txt Mon Apr 28 14:40:40 2014 -0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,23 +0,0 @@
-</app/product2/> a bt:Product, ldp:Container;
- ldp:membershipSubject <>;
- ldp:membershipPredicate bt:hasbug;
- ldp:membershipObject ldp:MemberSubject;
- dcterms:title "Product 2" ;
- dcterms:description "A container that tracks bugs of Product A" .
-
----
-
-{
- "@context": "https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-primer/context.json",
- "@id": "/app/product2/",
- "@type": [ "ldp:Container", "bt#Product"],
- "ldp:membershipSubject": "",
- "ldp:membershipObject": "ldp:MemberSubject",
- "ldp:membershipPredicate": "bt:hasbug",
- "dcterms:title": "Product 2",
- "dcterms:description": "A container that tracks bugs of Product A"
-}
-
-
-
-
\ No newline at end of file