Looking up a basic container (GET on an LDP-BC)

First Alice looks up her storage by retrieving the LDP Basic Container assigned to her to hold her documents. Alice's LDP client does this by doing a GET request on the URI, http://example.org/alice/.

As her document storage was just created, it is an empty container.

As shown in the example, in addition to the RDF representation of the Basic Container using the requested media type the server provides an etag of the resource representation and Link headers advertising that the requested resource is indeed an LDP Basic Container and it will support the LDP interaction model.

In addition, the response also contains "Allow" header which advertises which HTTP operations are supported by this LDP Basic Container resource. In this example, it supports OPTIONS,HEAD,GET,POST,PUT,PATCH HTTP verbs.

The Linked Data Platform 1.0 specification [[LDP]] says that all LDP servers MUST support the Turtle media type for LDP-RS resources and SHOULD support JSON-LD media type.

Discovering the affordances (OPTIONS on an LDP-BC)

In the previous example, we saw that Alice can discover what operations are allowed on a resource by doing a GET request on the resource. As an alternative, she can use the OPTIONS operation to learn of the permitted operations on any given resource.

 OPTIONS /alice/ HTTP/1.1
 Host: example.org      
      

HTTP/1.1 204 OK
Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
Accept-Post: text/turtle, application/ld+json, image/bmp, image/jpeg
Accept-Patch: example/patch
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel='type'     
      

According to the response, HTTP operations {OPTIONS,HEAD, GET,POST,PUT,PATCH} are allowed on her root container. In addition to the allowed operations, Accept-Post and Accept-Patch provides which media types are supported by the respective operations. The rel="type" Link header advertises that this resource supports LDP protocol and it is an LDP Basic Container.

In this case, the response tells Alice's LDP client 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).

Creating a RDF resource (POST an RDF resource to an LDP-BC)

Alice can upload a social profile document to her store, by POSTing her FOAF personal profile document to her LDP-BC at the root of her document store. Note, the Slug header offers the server a hint about URL of the resource to be created.

The FOAF document includes statements about the resource to be created and other resources relative to the resource to be created. According the LDP specification Alice can use null relative URI (<>) in the request entity body to refer to resource to be created.

 
HTTP/1.1 201 Created
Location: http://example.org/alice/foaf
Link: <http://www.w3.org/ns/ldp#Resource>; rel='type'
Content-Length: 0 
   

The response to the create request provides a Link to the newly created resource using the Location header. In this case, the server has honored the hint provided by the slug header and created the new resource in the URL http://example.org/alice/foaf.

Knowing the URL of the newly created resource, Alice can check the container again to confirm that the container correctly contains the newly created resource.

    GET /alice/ HTTP/1.1
    Host: example.org
    Accept: text/turtle, application/ld+json
     

     

       The ldp:contains containment triple discloses the newly created resource in the response. 
     

    

Creating a non-RDF (binary) resource (POST an image to an LDP-BC)

Next, Alice wants to upload a photo of herself to the document storage. She can create an image by POSTing it in the same way she created the RDF document.

 
POST /alice/ HTTP/1.1
Host: example.org
Slug: avatar
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: image/png
Content- Length: 1020

### binary data ###
   

 
HTTP/1.1 201 Created
Location: http://example.org/alice/avatar
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Link: <http://example.org/alice/avatar/meta>; rel="describedby"
Content-Length: 0   
   

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. Furthermore, in the case of binary resources the server may create an additional file to maintain the metadata about the binary file. In the above example, the server creates a new LDP-RS to maintain metadata about the binary resource such as creation date, owner, etc. and this metadata resource is advertised using a Link header with the relation "describedby".

Similar to creating a RDF resource (LDP-RS), a containment triple will be added to the container when a non-RDF (LDP-NR) is created. Thus, the representation of the LDP container after creating the image looks like the following.

Update a RDF LDP resource (PUT on an LDP-RS)

After creating the image as shown in the previous example, Alice now wants to update her FOAF profile with a link to the image. After retrieving her FOAF profile using a HTTP GET operation, she uses HTTP PUT to update the document by amending the RDF with a link to her photo.

In this example, Alice's LDP client sends the E-tag of the resource representation that it retrieved previously to prevent any lost update problems.

 
HTTP/1.1 204 No Content 
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type" 
      

If the operation is successful as shown above, the document will be updated with new information.

Alice can also use the PATCH operation to update the resource.

Deleting a resource (DELETE on an LDPR)

If Alice decides to delete the image, she can do that with a delete operation.

Similar to the previous update operation, Alice uses the etag of the resource representation she retrieved with If-Match header to do a conditional delete to ensure that the resource state was not changed since she decided to delete it.

 
DELETE /alice/avatar HTTP/1.1
Host: example.org
If-Match: W/"123454322"        
   

 
HTTP/1.1 204 No Content 
   

As well as deleting the resource, the server removes the containment triple from the container. For example, a subsequent GET request on the container will return a graph isomorphic to the one shown in the following representation::

For any subsequent request on the deleted resource, the server will respond with the appropriate HTTP response code.

    GET /alice/avatar HTTP/1.1
    Host: example.org
    Accept: image/png
     

 
HTTP/1.1 410 Gone 
   

Structural Manipulation (Child Containers)

In order for the client to introduce hierarchy to the management of documents, the document store allows creation of documents which are containers. That enables Alice to create a container hierarchy to organise her documents. This can be done by POSTing (a child) container representation to a (parent) container. This enables Alice to create a child container which she intends to use for image storage.

To create a new container for managing photos, Alice POSTs a representation of a container (LDP-BC) to the root container. Alice express her intention that the newly created resource should be an LDP Basic Container by including a Link header in the request with the relationship 'type'.

If the create is successful, the server responds with location of the newly created container for the photos.

HTTP/1.1 201 Created
Location: http://example.org/alice/photos/
Content-Length: 0  
        

After creation of this new container, the parent container will look like

and the photo container will look like the following.

Navigation and Retrieval (GET on an LDP-DC)

One of the main use cases of the example bug tracker is to list a given product's bugs. Assuming that a user got a URL of a product by out of band means, she can look it up to get more information including the bugs associated with it. To get the description of the product, a user (or her LDP client) can do a GET request on the URI of the known product resource. LDPR servers must provide text/turtle representations of the requested LDPRs and may provide other RDF format representations such as JSON-LD or RDF/XML using standard HTTP content negotiation.

If the product resource is available, the server responds with the RDF representation of the Direct Container that corresponds to the given product using the requested media type, text/turtle or application/ld+json in this case.

The representation of the product contains both information about the product such as the title and the bugs associated with the product and information about the product description such as the title of the product description and other properties of the LDP Container.

As you can see from the Link Header that is returned and the RDF representation of the container, this example uses an LDP Direct Container. LDP-DCs contain both containment triples and membership triples and provide the flexibility to the applications to use domain specific vocabulary in the membership triples. For example, in the above example the LDP-DC manages the member relationship, (<?productURI>, bt:hasBug, <?bugURI>), using the application-specific vocabulary term, bt:hasBug. This is done by defining the ldp:hasMemberRelation predicate of the Direct Container to bt:hasBug (<?directContainerURI>, ldp:hasMemberRelation, bt:hasbug).

The Direct Container shown in the above example has the membership triple pattern ( membership-constant-URI , membership-predicate , member-derived-URI ) using ldp:hasMemberRelation where the constant membership resource is in the subject of the triple and the newly created resources will be added as the object of the triple. It is also possible for the Direct Container to have the membership triple pattern ( member-derived-URI , membership-predicate , membership-constant-URI ) using ldp:isMemberOfRelation predicate where the constant member resource will be the object of the triple and the newly created resource will be added as the subject of the triple.

In addition, in this example the bugs are associated with the product resource (a non-information resource with a # URI) and not with the product description Direct Container itself. This is done by defining the ldp:membershipResource predicate of the LDP Direct Container as the product non-information resource URI (<?directContainerURI>, ldp:membershipResource, </tracker/product1/#it>). By doing so one can define the subject of the membership triple any resource of interest.

The next example illustrates the behaviour of LDP Direct containers when new resources are created and how aforementioned predicates of the Direct Containers affect the interaction model of LDP.

Creation (POST a resource to an LDP-DC)

Continuing from the previous example, we can report a Bug against the "LDP Demo" product by creating a Bug report (an LDPR representing the bug) under the "LDP Demo" product description LDPC by posting a RDF representation of the Bug report to the LDPC associated with the product description.

The bug report document includes statements about the resource to be created. According the LDP specification, a client can use null relative URI (<>) in the request entity body to refer to resource to be created.

If the creation is successful, the server responds with location of the newly created resource.

HTTP/1.1 201 Created
Location: http://example.org/tracker/ldp-demo/bug67
Content-Length: 0           
      

If the creation fails, the server will respond with an appropriate status code depending on the error. If successful, the LDP Demo product description LDPC will have the following representation after the creation of new resource.

As you can see two new triples are added to the container. That is (</tracker/ldp-demo/>, <ldp:contains>, </tracker/ldp-demo/bug67>) and (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67>). The former is added in any type of container and the latter is defined by the direct container properties.

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 POSTed.

Deletion (DELETE on an LDPR associated with an LDP-DC)

 DELETE /tracker/ldp-demo/bug3 HTTP/1.1 
 Host: example.org
 If-Match: W/"123454322"
        

If the delete is successful, the server will respond with a success status code.

 HTTP/1.1 204 No Content
        

After the deletion, the representation of the container will look like the following

As seen from the LDP Direct Container representation above, both the containment triple (</tracker/ldp-demo/>, ldp:contains, </tracker/ldp-demo/bug3>) and the membership triple (</tracker/ldp-demo/#it>, bt:hasBug, </tracker/ldp-demo/bug3>) were removed from the container representation.

Navigation and Retrieval (GET on an LDP-IC)

Similar to the previous LDP-DC example, first we will retrieve the representation of the LDP Indirect Container.

As a response to the GET request, the server responds with the representation of the product description container.

Now the product container is a LDP Indirect container, which has one main difference: the container has an additional predicate called "ldp:insertedContentRelation". Further, the objects of the containment triples and the membership triples are not the same. While the object of the containment triple is the same (e.g. </tracker/ldp-demo/bug3>, an information resource) the object of the membership triple is now (e.g. </tracker/ldp-demo/bug3#it>, a non-information resource or real world thing). This distinction is because of the ldp:insertedContentRelation definition. How this works will be explained in the next example on creating a new resource.

Creation (POST a resource to an LDP-IC)

Continuing from the previous example, we can create a new Bug Report against the 'LDP demo' product by creating a Bug Report LDPR under the 'LDP Demo' product description LDPC.

The client POSTs a representation of a Bug Report to the Bug Tracker LDPC.

One thing to note is that the representation of the resource to be created contains a triple (< >, foaf:primaryTopic , <#it>). If the create request is successful, the server responds with location of the newly created resource.

HTTP/1.1 201 Created
Location: http://example.org/tracker/ldp-demo/bug67
Content-Length: 0           
      

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.

As you can see, two new triples are added to the container. That is (</tracker/ldp-demo/>, <ldp:contains>, </tracker/ldp-demo/bug67>) and (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67#it>).