--- a/ldp-primer/ldp-primer.html Mon Apr 21 08:55:42 2014 -0400
+++ b/ldp-primer/ldp-primer.html Thu Apr 24 18:17:42 2014 +0200
@@ -11,29 +11,31 @@
most simplest type that is LDP Basic Container. The other types of containers will be explained later in the primer.
</p>
<p>
Elements of the collection of which are denoted by ldp:contains predicate shows the information documents contained by the LDP Container. These elements does not have to
- be LDPRs. Any HTTP resource can be contained in an LDPC. For example,
</p>
<table>
<tr>
<td class="col1"><img src="photos.png" /></td>
<td>
<pre title="An example LDPC with non-LDPRs" class='example' data-include='ldpc_ex_non_ldpr.txt' data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<p>
Use cases that motivated LDP specification varies from just publishing a dataset as Linked Data with advanced features as pagination,
providing read/write access to using Linked Data for application integration. The Linked Data Platform Use Cases and Requirements document provides
a more detailed information on the use cases that motivated the LDP specification.
</p>
<p>There will be several categories of systems implementing the LDP specification. Two main categories of the LDP servers include:</p>
<dl class="glossary">
<dt>Generic / vanilla LDP servers</dt>
<dd>RDF storage systems that allow interacting with their resources by means of the LDP specification. These servers do not impose any restriction on LDPRs.</dd>
<dt>Application specific LDP severs </dt>
<dd>Systems exposing their data using the LDP specification. These systems impose restrictions on LDPRs since they have an underlying business logic and data model.</dd>
</dl>
</section>
+ be LDPRs. Any HTTP resource can be contained in an LDPC. For example,
</p>
<table>
<tr>
<td class="col1"><img src="photos.png" /></td>
<td>
<pre title="An example LDPC with non-LDPRs" class='example' data-include='ldpc_ex_non_ldpr.txt' data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<p>
Use cases [[LDP-UCR]] that motivated LDP specification varies from just publishing a dataset as Linked Data with advanced features as pagination,
providing read/write access to using Linked Data for application integration. The Linked Data Platform Use Cases and Requirements document provides
a more detailed information on the use cases that motivated the LDP specification.
</p>
<p>There are several categories of systems implementing the LDP specification. Two main categories of LDP servers include:</p>
<dl class="glossary">
<dt>Generic / vanilla LDP servers</dt>
<dd>RDF storage systems that allow interacting with their resources by means of the LDP specification. These servers do not impose any restriction on LDPRs and generally act as storage systems without any domain
+ specific application logic and vocabularies. The document storage system in the first example of the primer falls into this category. </dd>
<dt>Application specific LDP severs </dt>
<dd>Existing applications with their own data model and business logic exposing their data using the LDP specification. These systems impose restrictions on LDPRs since the LDP interaction should be compliant with the underlying
+ business logic and data model. The bug tracker example presented in the latter part of the primer is an example of an application specific LDP server.</dd>
</dl>
</section>
- <section id="filesystem">
<h1>File System Example (LDP-RS / LDP-NR / LDP-BasicContainer)</h1>
+ <section id="photomanager">
<h1>Online document store example (LDP Basics)</h1>
<p>
- This section provides a set of examples of examples using a file system like read / write data storage on the Web that uses a Linked Data Platform protocol. These examples will
+ This section provides a set of examples of using an online document store application that provides read / write data storage on the Web using the Linked Data Platform protocol. These examples will
demonstrate the behaviour of LDPRs including both LDR-RSs (which have RDF representations) and LDP-NRs (which do not have RDF representations such as binary resources) and LDP Basic
Containers.
- When you register in example data storage system, you will get your data storage space (a root Basic Container) where you can store all sort of web resources that are supported by
- Linked Data Platform such as RDF resources (LDP-RS) and binary resources (LDP-NR). Using this root Basic Container you can create new files (documents) and also child containers to
- organize the documents.
+ When one registers in the document store application, she will get some data storage space (a root Basic Container) where she can store all sorts of web resources that are supported by
+ Linked Data Platform such as RDF resources (LDP-RS) and binary resources (LDP-NR). Using this root Basic Container she can create new documents and also child containers to
+ organize these documents.
</p>
<table class="simple">
<thead>
<th>Path</th>
<th>Method</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td rowspan="5">/{username}/</td>
<td>GET</td>
<td>Lists all the documents in the root container. </td>
</tr>
<tr>
<td>POST</td>
<td>Create a new document under the root container.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the description and/or list of files of the root container.</td>
</tr>
<tr>
<td>PATCH</td>
<td>Update the description and/or list of files of the root container.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Not allowed.</td>
</tr>
<tr>
<td class="col1" rowspan="5"><div class='code'>/{username}/{document*}/</div></td>
<td>GET</td>
<td>Retrive the document.</td>
</tr>
<tr>
<td>POST</td>
<td>Not allowed</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the document.</td>
</tr>
<tr>
<td>PATCH</td>
<td>Partial update to the document if PATCH is supported.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Delete the project description and associated bug reports.</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>
- <p class="note"> In the above API description, {document*} is considered a non-Container. The child containers such as /{username}/{ldp-bc}/ or /{username}/**/{ldp-bc}/ behave similar to the root container
+ <p class="note"> In the above API description, {document*} is considered a non-Container. The child containers such as /{username}/{ldpc}/ or /{username}/**/{ldpc}/ behave similar to the root container
/{username}/ except for that fact, deleting those child containers are allowed. </p>
- In this example, we will see how Alice, a user of this system, manages the read / write document storage using the LDP protocl.
+ In this example, we will see how Alice, a user of this system, manages the read / write document storage using the LDP protocol.
<p>First, Alice registers in the system and she is given a space that she can store her documents (She could use LDP protocol to register herself by POSTing to a container of users
- but that is out of scope of this example). When she registers she is informed that her document space is http://data.example.org/alice/. </p>
+ but that is out of scope of this example). When she registers she is informed the starting point URL to manage her documents, a basic container, http://data.example.org/alice/. </p>
<section id="filelookup">
<h2>Looking up a basic container (GET on an LDP-BC) </h2>
@@ -108,23 +110,151 @@
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>
- <section>
- <h2> Creating a 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>
<section id="bugtracker">
<h1>Bug Tracker Example (LDP-DirectContainer)</h1>
<p>
This section provides a set of examples to show the Linked Data Platform interactions. Note, this is a primer and should
not be considered as a canonical example of ideal LDP modeling.
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. We can re-use simple domain vocabulary,
e.g. has_bug or related, to express our data. 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>
<p class="note">Do we want to say something about suggested, user-friendly URIs ? </p>
<section id="navandret">
<h2>Navigation and Retreival</h2>
<b>Lookup a Product (LDPC?)</b>
<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>
<table>
<tr>
<td class="col1"><img src="product_lookup.png" /></td>
<td>
<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>
</td>
</tr>
</table>
<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.
</p>
<p>Looking up a bug is similar to looking up a product. </p>
<table>
<tr>
<td class="col1"><img src="bug_lookup.png" /></td>
<td>
<p>Based on links in the representation of the Product, the client uses GET to navigate to a known Bug resource.</p>
<pre class="example" title="Bug lookup request"
data-include='bug_look_up_req.txt' data-oninclude='fixCode'></pre>
<p>The server responds with the representation of the bug.</p>
<pre title="Bug lookup response"
class='example' data-include='bug_look_up_resp.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugCreate">Creation</h3>
<p>Continuing from the previous example, we can report a Bug against 'product1' by creating a Bug LDPR under the 'Product' LDPC.
The client POSTs a representation of a Bug to the Bug Tracker LDPC. </p>
<table>
<tr>
<td class="col1"><img src="bug_create.png" /></td>
<td>
<p>The client POSTs a representation of a Bug to the Bug Tracker LDPC.</p>
<pre title="A request for creating a bug"
class='example' data-include='bug_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="A response of creating new a bug"
class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /app/product1/67
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="product_postcreate.png" /></td>
<td>
<p>If the creation fails, the server will respond with an appropriate status code depending on the error.
After the resource is creation, the Product A LDPC will have the following representation.</p>
<pre title="The state of the product LDPC after the bug creation"
class='example' data-include='bug_create_s1.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td class="col1"><img src="bug67.png" /></td>
<td>
<p>And the created Bug resource will have the following representation. Note that server has added a
server managed property, creation date (dcterms:created), and a default value for the state (bt:isInState)
to the Bug in addition to what was being POSTed.</p>
<pre title="The state of the bug LDPR"
class='example' data-include='bug_create_s2.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugUpdate">Update</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="bug_update.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A request for updating a bug"
class='example' data-include='bug_update_req.txt'
data-oninclude='fixCode'></pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugDelete">Deletion</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="bug_delete.png" /></td>
<td>
<p>TODO - Description</p>
<pre class="example">
DELETE /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="meta-structure">Structural Manipulation</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>
<table>
<tr>
<td class='col1'><img src="app.png" /></td>
<td>
<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>
</td>
</tr>
<tr>
<td class="col1"><img src="app_post.png" /></td>
<td>
<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>
</td>
</tr>
<tr>
<td></td><td>
<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>
</td>
</tr>
</table>
</section>
<section>
<h3 id="ProductLookup">Operation Discovery</h3>
<p>
Assuming that a user got the URL of the product by out of band means, a starting point would be to discover
which operations can be performed on the product resource.
</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client does an OPTIONS with the URI of a known product description resource.</p>
<pre class="example">OPTIONS /app/product1/ HTTP/1.1
Host: example.org
</pre>
<p>If the product description resource is available, the server responds with the allowed HTTP operations on the product
resource along with some other metadata.</p>
<div class="turtle">
<pre title="HTTP response for OPTIONS on a product" class='example'>
HTTP/1.1 200 OK
Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
Accept-Post: text/turtle, application/ld+json
Accept-Patch: example/patch
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: <?nonMemberProperties>;rel="http://www.w3.org/ns/ldp#nonMemberResource"
Content-Length: 0
</pre>
</div>
</td>
</tr>
</table>
<p> According to the response, HTTP operations {OPTIONS,GET,POST,PUT,PATCH} are allowed on the product description resource.
In addition to the allowed operations, Accept-Post and Accept-Patch provides which media types are supported by respective operations.
The rel="type" Link header advertises that this is resource supports LDP protocol and the the rel="ldp:nonMemberResource" provides a link
to the non-member resource of this product description.
</p>
</section>
<section id="paging">
<h3>Pagination</h3>
<p>It sometimes happens that a resource is too large to reasonably transmit its representation in a single HTTP response. For example, if the
bug resource in our example includes comments, It might happen that it may be become too large. To address this problem, LDPRs should support
a technique called Paging.</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>If a client does a get on an LDPR that supports paging, it will be redirected to the first page of the resource.</p>
<pre class="example">
GET /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<pre class="example">
HTTP/1.1 303 See Other
Location: /app/product1/bug3?firstpage
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>Alternatively if the client wants to know in advance whether the resource is paged or not, it can do an OPTIONS request on the LDPR URI</p>
<pre class="example">
OPTIONS /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<p>If the resource is paged, the response contains a HTTP Link header with rel="first"; and the target URI of that header would be the URL of
the first page resource. </p>
<pre class="example">
HTTP/1.1 200 OK
Allow: OPTIONS,HEAD,GET,PUT,PATCH
Accept-Patch: example/patch
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: </app/product1/bug3?firstpage>; rel="first"
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>After knowing the URL of the first page resource, the client can retrieve it using a HTTP GET</p>
<pre class="example">
GET /app/product1/bug3?firstpage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="HTTP response for getting the first page resource"
class='example' data-include='paging_page1_res.txt'
data-oninclude='fixCode'></pre>
<p>The first page contains a link to the second page with LDPR as the subject,
ldp:nextPage as the predicate and the subsequent page as the object.</p>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The second page can be retrieved the same way as the first page was retrieved.</p>
<pre class="example">
GET /app/product1/bug3?secondPage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="HTTP response for getting the second page resource"
class='example' data-include='paging_page2_res.txt'
data-oninclude='fixCode'></pre>
<p>The last page of resource contains with LDPR as the subject,
ldp:nextPage as the predicate and the rdf:nil as the object.</p>
</td>
</tr>
</table>
</section>
<section id="odering">
<h3>Ordering</h3>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>There are many cases where an ordering of the members of the container is important. </p>
<pre class="example">
GET /app/product1?firstPage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="The representation of an ordered LDPC"
class='example' data-include='ordered_ldpc_resp.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section id="binary-res">
<h3>Binary resources</h3>
<b>Creating a binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>We have an LDPC which we can use to create binary resources</p>
<pre title="The state of the attachments LDPC"
class='example' data-include='attachments_s1.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td><img src="replace.png" /></td>
<td>
<p>The client POSTs a binary resource to the LDPC</p>
<pre title="A request for creating a product"
class='example'>POST /app/product1/bug3/attachments/ HTTP/1.1
Host: example.org
Content-Type: image/png
Slug: login-page.png
Content-Length: 1254
#### binary data #####
</pre>
<p>If the create is successful, the server it responds with a Location header and a Link header to
the automatically created metadata LDPR.</p>
<pre title="A response after creating new a binary resource" class='example'>HTTP/1.1 201 Created
Location: /app/product1/bug3/attachments/login-page.png
Link: </app/product1/bug3/attachments/1>; rel="meta"
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td></td>
<td>
<p>After the creation, LDPC representation looks like</p>
<pre title="The state of the attachments LDPC after creation"
class='example' data-include='attachments_s2.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<b>Accessing the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client can retrieve the binary resource by doing a GET on the binary resource URI.</p>
<pre class="example">GET /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
Accept: image/png
</pre>
<p>LDPR server responds with</p>
<pre title="HTTP response for getting the binary resource"
class='example'>HTTP/1.1 200 OK
Content-Type: image/png
Link: </app/product1/bug3/attachments/1>; rel="meta"
ETag: W/"123456789"
#### binary data #####
</pre>
</td>
</tr>
</table>
</section>
<b>Accessing the metadata about the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client can retrieve the metadata of the binary resource by doing a GET on the metadata-LDPR URI.</p>
<pre class="example">GET /app/product1/bug3/attachments/1
Host: example.org
Accept: text/turtle
</pre>
<p>LDPR server responds with</p>
<pre title="HTTP response for getting the binary resource"
class='example' data-include='attachments_m_get_res.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<b>Updating the metadata about the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO</p>
<pre title="Updating the metadata of the binary resource"
class='example' data-include='attachments_m_update_req.txt'
data-oninclude='fixCode'></pre>
<p>LDPR server responds with</p>
<pre class="example">HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<b>Deleting the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO</p>
<pre class="example"> DELETE /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
<pre class="example">GET /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 410 Gone
</pre>
<pre class="example"> GET /app/product1/bug3/attachments/1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 410 Gone
</pre>
</td>
</tr>
</table>
</section>
</section>
</section>
<section>
<h1 id="advexamples">Advanced Examples</h1>
<section>
<h3 id="ldpmemx">Uses of membership{Subject,Predicate,Object} predicates </h3>
<p>In most of the previous examples we kept the ldp:membershipSubject as the LDPC itself and ldp:membershipObject as the ldp:MemberSubject. However, these
predicates can be used to change the semantics of the membership relationship in LDPCs. </p>
<p class="note">TO DO: A small note on document vs Thing separation linking to <a href="http://www.w3.org/TR/webarch/#id-resources">Web Arch</a>,
, <a href="http://www.w3.org/TR/cooluris/#semweb">Cool URIs</a>, <a href="http://www.w3.org/TR/urls-in-data/#landing-pages">URLs in Data</a>.</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>If the separation between real world resource and information is important, the product description of the previous Bug Tracker example can
be alternatively designed as following.</p>
<pre title="Representation of the product description"
class='example' data-include='product_alt_s1.txt'
data-oninclude='fixCode'></pre>
<p>In the above example, the product description information resource is explicitly seperated from the real world product resource. Now the RDF representation
contains information about both the information resource that is identified by the URI </app/product1/> and the real world resource identified by the
URI </app/product1/#it>. </p>
<p>With this seperation, now the ldp:membershipSubject of the container is not the container URI itself but </app/product1/#it>. The effect of these is that
membership relation triples added when new resources are POSTed to this container will now have the subject </app/product1/#it> not the container URI. Further,
ldp:membershipObject of this container is foaf:primaryTopic. Thus, the object of the membership triple will not be the newly created resource but the foaf:primaryTopic
defined inside that newly created resource as shown in the following example. </p>
<pre title="HTTP request for creating a new bug report"
class='example' data-include='bug_alt_create_req.txt'
data-oninclude='fixCode'></pre>
<p>And the server will respond with the URI of the newly created information resource in the Location header.</p>
<pre title="Representation of the newly created bug"
class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /app/product1/67
Content-Length: 0
</pre>
<p>After the resource creation, the representations of the LDPC and newly created LDPR would be </p>
<pre title="Representation of the LDPC"
class='example' data-oninclude='fixCode' data-include='product_alt_s2.txt'></pre>
<pre title="Representation of the newly created bug"
class='example' data-oninclude='fixCode' data-include='bug_alt_s1.txt'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="mempredinv">ldp:membershipPredicateInverse predicate</h3>
<p>In sometimes the membership relationship can defined in a way such that the container is becomes the object of the membership triple. For example,
in our example, if the membership triple was like < bug, bt:relatedProduct, product > the product container would look like</p>
<pre title="Representation of an LDPC with ldp:membershipPredicateInverse predicate"
class='example' data-oninclude='fixCode' data-include='product_inv_s1.txt'></pre>
<p>TODO - Find a better example</p>
</section>
<section id="res-inlining">
<h3>Resource Inlining</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A HTTP request to a LDPR with inlined resources"
class='example' data-oninclude='fixCode' data-include='res_inline_req.txt'></pre>
<p> </p>
<pre title="A HTTP response from a LDPR with inlined resources"
class='example' data-oninclude='fixCode' data-include='res_inline_res.txt'></pre>
</td>
</tr>
</table>
</section>
<section id="mem-inlining">
<h3>Member Inlining</h3>
</section>
</section>
<section>
<h1>Security</h1>
<p class="note">Mention a little bit about security</p>
</section>
<section>
<h1 id="ldpc">LDP Implementations</h1>
A list of implementations that plan to be LDP compliant is available in the LDP Implementations wiki page.
LDP Implementation report provides the coverage of the specification by each LDP implementation.
</section>
<section>
<h1 id="next">What To Read Next</h1>
The primer only provide an overview of the Linked Data Platform specifications. LDP WG has produced following documents that contribute to the Linked Data Platform specification.
<ul>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/TR/ldp-ucr.html">Linked Data Platform Use Cases and Requirements</a> [[LDP-UCR]]</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp.html">Linked Data Platform 1.0 specifcation</a> [[LDP]]</li>
<li>Linked Data Platform 1.0 Primer (This document)</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-bp/ldp-bp.html">LDP Best Practices and Guidelines</a> [[LDP-BP]]</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/Test%20Cases/LDP%20Test%20Cases.html">Linked Data Platform 1.0 Test Cases</a>[[LDP-TESTS]]</li>
</ul>
</section>
<section class='appendix informative' id="history">
<h1>Change History</h1>
<p>The change history is up to the editors to insert a brief summary of
changes, ordered by most recent changes first and with heading from which
public draft it has been changed from.
</p>
<ul>
<li>2013-08-05 - Providing JSON-LD representations of the examples.</li>
<li>2013-07-03 - Moving the content from the wiki to the note.</li>
</ul>
</section>
</body>
</html>
\ No newline at end of file
+ </section>
<section id="bugtracker">
<h1>Bug Tracker Example (Direct and Indirect 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 Thing separation please refer to <a href="http://www.w3.org/TR/webarch/#id-resources">Web Arch</a>,
, <a href="http://www.w3.org/TR/cooluris/#semweb">Cool URIs</a>, <a href="http://www.w3.org/TR/urls-in-data/#landing-pages">URLs in Data</a>.</p>
+
<p>
This section provides a set of examples to show the Linked Data Platform interactions. Note, this is a primer and should
not be considered as a canonical example of ideal LDP modeling.
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. We can re-use simple domain vocabulary,
e.g. has_bug or related, to express our data. 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>
<p class="note">Do we want to say something about suggested, user-friendly URIs ? </p>
<section id="navandret">
<h2>Navigation and Retreival</h2>
<b>Lookup a Product (LDPC?)</b>
<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>
<table>
<tr>
<td class="col1"><img src="product_lookup.png" /></td>
<td>
<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>
</td>
</tr>
</table>
<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.
</p>
<p>Looking up a bug is similar to looking up a product. </p>
<table>
<tr>
<td class="col1"><img src="bug_lookup.png" /></td>
<td>
<p>Based on links in the representation of the Product, the client uses GET to navigate to a known Bug resource.</p>
<pre class="example" title="Bug lookup request"
data-include='bug_look_up_req.txt' data-oninclude='fixCode'></pre>
<p>The server responds with the representation of the bug.</p>
<pre title="Bug lookup response"
class='example' data-include='bug_look_up_resp.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugCreate">Creation</h3>
<p>Continuing from the previous example, we can report a Bug against 'product1' by creating a Bug LDPR under the 'Product' LDPC.
The client POSTs a representation of a Bug to the Bug Tracker LDPC. </p>
<table>
<tr>
<td class="col1"><img src="bug_create.png" /></td>
<td>
<p>The client POSTs a representation of a Bug to the Bug Tracker LDPC.</p>
<pre title="A request for creating a bug"
class='example' data-include='bug_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="A response of creating new a bug"
class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /app/product1/67
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="product_postcreate.png" /></td>
<td>
<p>If the creation fails, the server will respond with an appropriate status code depending on the error.
After the resource is creation, the Product A LDPC will have the following representation.</p>
<pre title="The state of the product LDPC after the bug creation"
class='example' data-include='bug_create_s1.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td class="col1"><img src="bug67.png" /></td>
<td>
<p>And the created Bug resource will have the following representation. Note that server has added a
server managed property, creation date (dcterms:created), and a default value for the state (bt:isInState)
to the Bug in addition to what was being POSTed.</p>
<pre title="The state of the bug LDPR"
class='example' data-include='bug_create_s2.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugUpdate">Update</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="bug_update.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A request for updating a bug"
class='example' data-include='bug_update_req.txt'
data-oninclude='fixCode'></pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="BugDelete">Deletion</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="bug_delete.png" /></td>
<td>
<p>TODO - Description</p>
<pre class="example">
DELETE /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="meta-structure">Structural Manipulation</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>
<table>
<tr>
<td class='col1'><img src="app.png" /></td>
<td>
<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>
</td>
</tr>
<tr>
<td class="col1"><img src="app_post.png" /></td>
<td>
<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>
</td>
</tr>
<tr>
<td></td><td>
<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>
</td>
</tr>
</table>
</section>
<section>
<h3 id="ProductLookup">Operation Discovery</h3>
<p>
Assuming that a user got the URL of the product by out of band means, a starting point would be to discover
which operations can be performed on the product resource.
</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client does an OPTIONS with the URI of a known product description resource.</p>
<pre class="example">OPTIONS /app/product1/ HTTP/1.1
Host: example.org
</pre>
<p>If the product description resource is available, the server responds with the allowed HTTP operations on the product
resource along with some other metadata.</p>
<div class="turtle">
<pre title="HTTP response for OPTIONS on a product" class='example'>
HTTP/1.1 200 OK
Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
Accept-Post: text/turtle, application/ld+json
Accept-Patch: example/patch
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: <?nonMemberProperties>;rel="http://www.w3.org/ns/ldp#nonMemberResource"
Content-Length: 0
</pre>
</div>
</td>
</tr>
</table>
<p> According to the response, HTTP operations {OPTIONS,GET,POST,PUT,PATCH} are allowed on the product description resource.
In addition to the allowed operations, Accept-Post and Accept-Patch provides which media types are supported by respective operations.
The rel="type" Link header advertises that this is resource supports LDP protocol and the the rel="ldp:nonMemberResource" provides a link
to the non-member resource of this product description.
</p>
</section>
<!-- section id="paging">
<h3>Pagination</h3>
<p>It sometimes happens that a resource is too large to reasonably transmit its representation in a single HTTP response. For example, if the
bug resource in our example includes comments, It might happen that it may be become too large. To address this problem, LDPRs should support
a technique called Paging.</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>If a client does a get on an LDPR that supports paging, it will be redirected to the first page of the resource.</p>
<pre class="example">
GET /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<pre class="example">
HTTP/1.1 303 See Other
Location: /app/product1/bug3?firstpage
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>Alternatively if the client wants to know in advance whether the resource is paged or not, it can do an OPTIONS request on the LDPR URI</p>
<pre class="example">
OPTIONS /app/product1/bug3 HTTP/1.1
Host: example.org
</pre>
<p>If the resource is paged, the response contains a HTTP Link header with rel="first"; and the target URI of that header would be the URL of
the first page resource. </p>
<pre class="example">
HTTP/1.1 200 OK
Allow: OPTIONS,HEAD,GET,PUT,PATCH
Accept-Patch: example/patch
Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
Link: </app/product1/bug3?firstpage>; rel="first"
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>After knowing the URL of the first page resource, the client can retrieve it using a HTTP GET</p>
<pre class="example">
GET /app/product1/bug3?firstpage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="HTTP response for getting the first page resource"
class='example' data-include='paging_page1_res.txt'
data-oninclude='fixCode'></pre>
<p>The first page contains a link to the second page with LDPR as the subject,
ldp:nextPage as the predicate and the subsequent page as the object.</p>
</td>
</tr>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The second page can be retrieved the same way as the first page was retrieved.</p>
<pre class="example">
GET /app/product1/bug3?secondPage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="HTTP response for getting the second page resource"
class='example' data-include='paging_page2_res.txt'
data-oninclude='fixCode'></pre>
<p>The last page of resource contains with LDPR as the subject,
ldp:nextPage as the predicate and the rdf:nil as the object.</p>
</td>
</tr>
</table>
</section !-->
<!-- section id="odering">
<h3>Ordering</h3>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>There are many cases where an ordering of the members of the container is important. </p>
<pre class="example">
GET /app/product1?firstPage HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
</pre>
<pre title="The representation of an ordered LDPC"
class='example' data-include='ordered_ldpc_resp.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section -->
<!-- section id="binary-res">
<h3>Binary resources</h3>
<b>Creating a binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>We have an LDPC which we can use to create binary resources</p>
<pre title="The state of the attachments LDPC"
class='example' data-include='attachments_s1.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td><img src="replace.png" /></td>
<td>
<p>The client POSTs a binary resource to the LDPC</p>
<pre title="A request for creating a product"
class='example'>POST /app/product1/bug3/attachments/ HTTP/1.1
Host: example.org
Content-Type: image/png
Slug: login-page.png
Content-Length: 1254
#### binary data #####
</pre>
<p>If the create is successful, the server it responds with a Location header and a Link header to
the automatically created metadata LDPR.</p>
<pre title="A response after creating new a binary resource" class='example'>HTTP/1.1 201 Created
Location: /app/product1/bug3/attachments/login-page.png
Link: </app/product1/bug3/attachments/1>; rel="meta"
Content-Length: 0
</pre>
</td>
</tr>
<tr>
<td></td>
<td>
<p>After the creation, LDPC representation looks like</p>
<pre title="The state of the attachments LDPC after creation"
class='example' data-include='attachments_s2.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<b>Accessing the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client can retrieve the binary resource by doing a GET on the binary resource URI.</p>
<pre class="example">GET /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
Accept: image/png
</pre>
<p>LDPR server responds with</p>
<pre title="HTTP response for getting the binary resource"
class='example'>HTTP/1.1 200 OK
Content-Type: image/png
Link: </app/product1/bug3/attachments/1>; rel="meta"
ETag: W/"123456789"
#### binary data #####
</pre>
</td>
</tr>
</table>
</section>
<b>Accessing the metadata about the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>The client can retrieve the metadata of the binary resource by doing a GET on the metadata-LDPR URI.</p>
<pre class="example">GET /app/product1/bug3/attachments/1
Host: example.org
Accept: text/turtle
</pre>
<p>LDPR server responds with</p>
<pre title="HTTP response for getting the binary resource"
class='example' data-include='attachments_m_get_res.txt'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<b>Updating the metadata about the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO</p>
<pre title="Updating the metadata of the binary resource"
class='example' data-include='attachments_m_update_req.txt'
data-oninclude='fixCode'></pre>
<p>LDPR server responds with</p>
<pre class="example">HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<b>Deleting the binary resource</b>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO</p>
<pre class="example"> DELETE /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
<pre class="example">GET /app/product1/bug3/attachments/login-page.png HTTP/1.1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 410 Gone
</pre>
<pre class="example"> GET /app/product1/bug3/attachments/1
Host: example.org
</pre>
<pre class="example">HTTP/1.1 410 Gone
</pre>
</td>
</tr>
</table>
</section>
</section !-->
</section>
<!-- section>
<h1 id="advexamples">Advanced Examples</h1>
<section>
<h3 id="ldpmemx">Uses of membership{Subject,Predicate,Object} predicates </h3>
+ <p class="note"> Now we can get rid of this section. </p>
+
+ <p>In most of the previous examples we kept the ldp:membershipSubject as the LDPC itself and ldp:membershipObject as the ldp:MemberSubject. However, these
predicates can be used to change the semantics of the membership relationship in LDPCs. </p>
<p class="note">TO DO: A small note on document vs Thing separation linking to <a href="http://www.w3.org/TR/webarch/#id-resources">Web Arch</a>,
, <a href="http://www.w3.org/TR/cooluris/#semweb">Cool URIs</a>, <a href="http://www.w3.org/TR/urls-in-data/#landing-pages">URLs in Data</a>.</p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>If the separation between real world resource and information is important, the product description of the previous Bug Tracker example can
be alternatively designed as following.</p>
<pre title="Representation of the product description"
class='example' data-include='product_alt_s1.txt'
data-oninclude='fixCode'></pre>
<p>In the above example, the product description information resource is explicitly seperated from the real world product resource. Now the RDF representation
contains information about both the information resource that is identified by the URI </app/product1/> and the real world resource identified by the
URI </app/product1/#it>. </p>
<p>With this seperation, now the ldp:membershipSubject of the container is not the container URI itself but </app/product1/#it>. The effect of these is that
membership relation triples added when new resources are POSTed to this container will now have the subject </app/product1/#it> not the container URI. Further,
ldp:membershipObject of this container is foaf:primaryTopic. Thus, the object of the membership triple will not be the newly created resource but the foaf:primaryTopic
defined inside that newly created resource as shown in the following example. </p>
<pre title="HTTP request for creating a new bug report"
class='example' data-include='bug_alt_create_req.txt'
data-oninclude='fixCode'></pre>
<p>And the server will respond with the URI of the newly created information resource in the Location header.</p>
<pre title="Representation of the newly created bug"
class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /app/product1/67
Content-Length: 0
</pre>
<p>After the resource creation, the representations of the LDPC and newly created LDPR would be </p>
<pre title="Representation of the LDPC"
class='example' data-oninclude='fixCode' data-include='product_alt_s2.txt'></pre>
<pre title="Representation of the newly created bug"
class='example' data-oninclude='fixCode' data-include='bug_alt_s1.txt'></pre>
</td>
</tr>
</table>
</section>
<section>
<h3 id="mempredinv">ldp:membershipPredicateInverse predicate</h3>
<p>In sometimes the membership relationship can defined in a way such that the container is becomes the object of the membership triple. For example,
in our example, if the membership triple was like < bug, bt:relatedProduct, product > the product container would look like</p>
<pre title="Representation of an LDPC with ldp:membershipPredicateInverse predicate"
class='example' data-oninclude='fixCode' data-include='product_inv_s1.txt'></pre>
<p>TODO - Find a better example</p>
</section>
<section id="res-inlining">
<h3>Resource Inlining</h3>
<p> TODO - Description </p>
<table>
<tr>
<td class="col1"><img src="replace.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A HTTP request to a LDPR with inlined resources"
class='example' data-oninclude='fixCode' data-include='res_inline_req.txt'></pre>
<p> </p>
<pre title="A HTTP response from a LDPR with inlined resources"
class='example' data-oninclude='fixCode' data-include='res_inline_res.txt'></pre>
</td>
</tr>
</table>
</section>
<section id="mem-inlining">
<h3>Member Inlining</h3>
</section>
</section !-->
<section>
<h1>Security</h1>
<p> It is not the focus of the Linked Data Platform WG to provide security mechanisms for read/write Linked Data applications. Though most of the security mechanisms that are applicable to
+ general web applications are equally applicable to Linked Data applications, there is still some space to build security mechanisms specific to Linked Data applications by leverage the Linked Data
+ technologies and providing concrete security requirements of Linked Data applications. In this context, LDP WG has started to create a WG note on Access Control which aims to produce use cases for
+ security scenarios of LDP applications that can be used as the input to later initiative that will be focused on developing standard security mechanisms for LDP applications. </p>
</section>
<section>
<h1 id="ldpc">LDP Implementations</h1>
A list of implementations that plan to be LDP compliant is available in the LDP Implementations wiki page. LDP Implementation report provides the coverage of the specification by each LDP implementation.
</section>
<section>
<h1 id="next">What To Read Next</h1>
The primer only provide an overview of the Linked Data Platform specifications. LDP WG has produced following documents that contribute to the Linked Data Platform specification.
<ul>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/TR/ldp-ucr.html">Linked Data Platform Use Cases and Requirements</a> [[LDP-UCR]]</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp.html">Linked Data Platform 1.0 specifcation</a> [[LDP]]</li>
<li>Linked Data Platform 1.0 Primer (This document)</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-bp/ldp-bp.html">LDP Best Practices and Guidelines</a> [[LDP-BP]]</li>
<li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/Test%20Cases/LDP%20Test%20Cases.html">Linked Data Platform 1.0 Test Cases</a>[[LDP-TESTS]]</li>
</ul>
</section>
<section class='appendix informative' id="history">
<h1>Change History</h1>
<p>The change history is up to the editors to insert a brief summary of
changes, ordered by most recent changes first and with heading from which
public draft it has been changed from.
</p>
<ul>
<li>2013-08-05 - Providing JSON-LD representations of the examples.</li>
<li>2013-07-03 - Moving the content from the wiki to the note.</li>
</ul>
</section>
</body>
</html>
\ No newline at end of file