Documents

In this guide, we’ll use different scenarios to go through the REST API methods (detailing the different headers and basic request bodies) you can use to interact with the Carbon LDP™ platform when creating or modifying Documents.

We have created a Postman Collection with all the examples featured in this documentation. The examples for this section are contained in the documents folder.

What is a Carbon LDP™ Document?

Carbon LDP stores its data in documents, these represent the basic structure to store any resource in your platform. Typically, a document represents a data entity of a given type (e.g. Person, Project, Product, Invoice). It can have any number of literal datatype properties (e.g. string, date, number) and links to other resources. Finally, within Carbon LDP™, documents are uniquely identified by Uniform Resource Identifiers (URIs).

The more you know…

In Carbon LDP™ a Document is a group of quads that share a common context.

To get a better insight into the basic parts that conform a Carbon LDP™ Document, see Document model.

Now let’s see how you can interact with documents in Carbon LDP™ through REST methods.

Create a Document

Issue a POST request through HTTP in order to create our first basic document.

Create the POST request

Create the following HTTP request to create a test document.

POST http://localhost:8083/

HTTP Header Value Required/Optional
Content-Type application/ld+json

or

application/trig

Required
Prefer http://www.w3.org/ns/ldp#Container; rel=interaction-model Optional
Accept application/ld+json

or

application/trig

Optional (default is text/turtle)
Slug test-document Optional
{
    "@context": {
        "c": { "@id": "https://carbonldp.com/ns/v1/platform#" },
        "ex": { "@id": "http://example.org/ns#" },
        "xsd": { "@id": "http://www.w3.org/2001/XMLSchema#" },
        "ex:literalProperty": {
            "@type": "xsd:string"
        },
        "ex:numericalProperty": {
            "@type": "xsd:int"
        }
    },
    "@id": "",
    "@type": [ "c:Document" ],
    "ex:literalProperty": "Example property",
    "ex:numericalProperty": "1"
}
@prefix c: <https://carbonldp.com/ns/v1/platform#> .
@prefix ex: <http://example.org/ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<>{
    <>
        a c:Document ;
        ex:literalProperty "Example property" ;
        ex:numericalProperty "1"^^xsd:int .
}

Review the POST request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Content-Type

Since the request method is POST it requires a body. Therefore, the Content-Type HTTP header tells the platform what kind of content to expect in the body of the request. In the examples we use either JSON-LD (application/ld+json) or TriG (application/trig) RDF Dataset Languages because they are brief and also support named graphs. Whether you decide to use JSON-LD or the TriG language, you’ll find that each one provides their own advantages. If you’re familiar with JSON objects and JavaScript you might find JSON-LD easier to understand. On the other hand, you might find TriG a bit less verbose and easier to read when it comes to identifying specific RDF structures.

Note that Carbon LDP also supports other content types for RDF such as:

  • Turtle: text/turtle
  • RDF XML: application/rdf+xml
Prefer

The Prefer header uses a link relation to specify the interaction model of the target resource. When you issue a request, you are targeting a specific resource where your request will be applied; in this case the root (/) resource. By specifying its interaction model, we’re defining how we want the root resource to behave.

In Carbon LDP resources can behave as either Documents (RDFSource) or Containers. When you’re creating a document, you want the target resource to interact as a Container. Because we’re adding a member resource to the container, we need it to behave like a container as opposed to an RDFSource. Carbon LDP supports the following interaction model values for the Prefer header:

  • http://www.w3.org/ns/ldp#Container; rel=interaction-model
  • http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model

ldp:Container is the default interaction model used by the platform. Therefore, the inclusion of this header in the request is optional.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use the same format used to send the request body. If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json
Slug

The Slug header is intended to give the server a hint about how to mint a new URI for the resource being created. If a slug is not provided, Carbon LDP will generate a random number when minting the URI. In this case, however, we’re specifying a preference to use test-document. Therefore, if it is available for use, the server will mint the following URI:

http://localhost:8083/test-document/

If the URI you’re trying to create already exists, the platform will respond with a 409 Conflict HTTP status code. Keep in mind that URIs are unique identifiers, therefore, the platform will not allow you to create a duplicate resource.

Body

The body of the request is a graph of triples written in the RDF syntax matching the Content-Type header.

If there is anything from the request body you don’t understand you can check the JSON-LD or TriG W3C specifications, which Carbon LDP complies to.

Issue the POST request

A successful request will result in HTTP status code 201 Created.

HTTP Header Value
ETag “-1122003795”
Location http://localhost:8083/test-document/

As part of the response headers:

  • The ETag header will confirm the time of the document’s creation.
  • The Location header will provide the server minted URI for the new document.

Retrieve a Document

You can now examine the newly created resource by issuing a GET request to the URI that was minted for it.

Create the GET request

Create the following HTTP request to retrieve the Document we created in the previous section.

GET http://localhost:8083/test-document/

HTTP Header Value Required/Optional
Accept application/ld+json
or
application/trig
Optional (default is text/turtle)

The more you know…

Note the trailing slash in the URI. Remember that an RDFSource created in Carbon LDP is automatically also a Container (a feature Carbon LDP manages for you), so the server-minted URI always ends with a trailing slash.

Review the GET request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use the same format used to send the request body.
If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json

Issue the GET request

A successful request will result in HTTP status code 200 OK.

HTTP Header Value
ETag “-1122003795”
[
    {
        "@graph": [
            {
                "@id": "http://localhost:8083/test-document/",
                "@type": [
                    "http://www.w3.org/ns/ldp#BasicContainer",
                    "https://carbonldp.com/ns/v1/platform#Document",
                    "http://www.w3.org/ns/ldp#RDFSource"
                ],
                "http://example.org/ns#literalProperty": [
                    {
                        "@value": "Example property"
                    }
                ],
                "http://example.org/ns#numericalProperty": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#int",
                        "@value": "1"
                    }
                ],
                "http://www.w3.org/ns/ldp#hasMemberRelation": [
                    {
                        "@id": "http://www.w3.org/ns/ldp#member"
                    }
                ],
                "http://www.w3.org/ns/ldp#insertedContentRelation": [
                    {
                        "@id": "http://www.w3.org/ns/ldp#MemberSubject"
                    }
                ],
                "http://www.w3.org/ns/ldp#membershipResource": [
                    {
                        "@id": "http://localhost:8083/test-document/"
                    }
                ],
                "https://carbonldp.com/ns/v1/platform#created": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
                        "@value": "2017-11-29T12:28:31.547-06:00"
                    }
                ],
                "https://carbonldp.com/ns/v1/platform#modified": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
                        "@value": "2017-11-29T12:28:31.547-06:00"
                    }
                ]
            }
        ],
        "@id": "http://localhost:8083/test-document/"
    }
]
<http://localhost:8083/test-document/> {
    <http://localhost:8083/test-document/> a <http://www.w3.org/ns/ldp#BasicContainer> , <https://carbonldp.com/ns/v1/platform#Document> , <http://www.w3.org/ns/ldp#RDFSource> ;
        <https://carbonldp.com/ns/v1/platform#created> "2017-11-29T12:28:31.547-06:00"%22<http://www.w3.org/2001/XMLSchema#dateTime> ;
        <https://carbonldp.com/ns/v1/platform#modified> "2017-11-29T12:28:31.547-06:00"%22<http://www.w3.org/2001/XMLSchema#dateTime> ;
        <http://www.w3.org/ns/ldp#membershipResource> <http://localhost:8083/test-document/> ;
        <http://www.w3.org/ns/ldp#hasMemberRelation> <http://www.w3.org/ns/ldp#member> ;
        <http://www.w3.org/ns/ldp#insertedContentRelation> <http://www.w3.org/ns/ldp#MemberSubject> ;
        <http://example.org/ns#literalProperty> "Example property" ;
        <http://example.org/ns#numericalProperty> "1"%22<http://www.w3.org/2001/XMLSchema#int> .
}

As part of the response headers:

  • The ETag will confirm the last time the document resource has been modified.

Since we haven’t altered the document it should be the same as the one we got when creating the Document. Nevertheless, whenever the resource is modified the ETag will be updated.

The response will also include a body where you will find your Document structure in the format you set on the Accept header.

While JSON-LD is a great response format to process JavaScript, it can be a tad verbose. Therefore, you may find TriG a bit more useful, specially since it facilitates reading statements in the shape of Subject, Predicate, and Object. Note that you can issue the same GET request using any other supported RDF syntax for the Accept header.

Review the GET response

If you inspect the response body a bit more, you’ll realize that your document now contains more properties and types than what you may have originally defined.

The platform automatically adds some properties to your document, some of them are System Reserved Properties, for example c:created or c:modified. While these properties might be useful when implementing certain functionalities, keep in mind that they can’t be set or modified by your program.

Furthermore, the platform automatically adds certain types to the resources it creates, for example ldp:BasicContainer and ldp:RDFSource. This allows for resources to behave in multiple ways, as we have mentioned before. Additionally, if we hadn’t defined the c:Document type the platform would have added it automatically in this case, based on the interaction model we used when creating the resource.

Modify a Document

You can modify a resource using either a PUT or a PATCH request. Keep in mind that a PUT method replaces the entire resource with your request body. On the other hand, the PATCH method should contain a set of instructions on how to partially modify your resource. Let’s analyze both requests in more detail modifying the Document we have been using in the previous examples.

Using a PUT request

When you use a PUT request to modify a resource you are replacing the one contained in the server with the content of your request body. Let’s see an example where we want to modify a property and include a new type in the test-document we created and read in the previous examples with a PUT request.

We will modify the ex:literalProperty value from “Example property” to “Modified example property”, and we will add a type ex:PUTExample to our document.

Create the PUT request

Create the following HTTP request to modify the test-document we have been working with.

PUT http://localhost:8083/test-document/

HTTP Header Value Required/Optional
Content-Type application/ld+json
or
application/trig
Required
Prefer http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model Required
If-Match “-1122003795” (latest ETag obtained from the resource) Required
Accept application/ld+json
or
application/trig
Optional
[
    {
        "@context":{
            "ex": { "@id": "http://example.org/ns#" }
        },
        "@graph": [
            {
                "@id": "http://localhost:8083/test-document/",
                "@type": [
                    "http://www.w3.org/ns/ldp#BasicContainer",
                    "https://carbonldp.com/ns/v1/platform#Document",
                    "http://www.w3.org/ns/ldp#RDFSource",
                    "ex:PUTExample"
                ],
                "http://example.org/ns#literalProperty": [
                    {
                        "@value": "Modified example property"
                    }
                ],
                "http://example.org/ns#numericalProperty": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#int",
                        "@value": "1"
                    }
                ],
                "http://www.w3.org/ns/ldp#hasMemberRelation": [
                    {
                        "@id": "http://www.w3.org/ns/ldp#member"
                    }
                ],
                "http://www.w3.org/ns/ldp#insertedContentRelation": [
                    {
                        "@id": "http://www.w3.org/ns/ldp#MemberSubject"
                    }
                ],
                "http://www.w3.org/ns/ldp#membershipResource": [
                    {
                        "@id": "http://localhost:8083/test-document/"
                    }
                ],
                "https://carbonldp.com/ns/v1/platform#created": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
                        "@value": "2017-11-29T12:28:31.547-06:00"
                    }
                ],
                "https://carbonldp.com/ns/v1/platform#modified": [
                    {
                        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
                        "@value": "2017-11-29T12:28:31.547-06:00"
                    }
                ]
            }
        ],
        "@id": "http://localhost:8083/test-document/"
    }
]
@prefix ex:<http://example.org/ns#> .

<http://localhost:8083/test-document/> {
    <http://localhost:8083/test-document/> a <http://www.w3.org/ns/ldp#BasicContainer> , <https://carbonldp.com/ns/v1/platform#Document> , <http://www.w3.org/ns/ldp#RDFSource>  <ex:PUTExample;
        <https://carbonldp.com/ns/v1/platform#created> "2017-11-29T12:28:31.547-06:00"%22<http://www.w3.org/2001/XMLSchema#dateTime> ;
        <https://carbonldp.com/ns/v1/platform#modified> "2017-11-29T12:28:31.547-06:00"%22<http://www.w3.org/2001/XMLSchema#dateTime> ;
        <http://www.w3.org/ns/ldp#membershipResource> <http://localhost:8083/test-document/> ;
        <http://www.w3.org/ns/ldp#hasMemberRelation> <http://www.w3.org/ns/ldp#member> ;
        <http://www.w3.org/ns/ldp#insertedContentRelation> <http://www.w3.org/ns/ldp#MemberSubject> ;
        <http://example.org/ns#literalProperty> "Modified example property" ;
        <http://example.org/ns#numericalProperty> "1"%22<http://www.w3.org/2001/XMLSchema#int> .
}

The more you know…

Note the trailing slash in the URI. Remember that an RDFSource created in Carbon LDP is automatically also a Container (a feature Carbon LDP manages for you), so the server-minted URI always ends with a trailing slash.

Review the PUT request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Content-Type

Since the request method is PUT it requires a body. Therefore, the Content-Type HTTP header tells the platform what kind of content to expect in the body of the request. In the examples we use both JSON-LD (application/ld+json) and TriG (application/trig) RDF Dataset Languages because they are brief and also support named graphs. Whether you decide to use JSON-LD or the TriG language, you’ll find that either one provides their own advantages. If you’re familiar with JSON objects and JavaScript you might find JSON-LD easier to understand. On the other hand, you might find TriG a bit less verbose and easier to read when it comes to identifying specific RDF structures.

Note that Carbon LDP also supports other content types for RDF such as:

  • Turtle: text/turtle
  • RDF XML: application/rdf+xml
Prefer

The Prefer header uses a link relation to specify the interaction model of the target resource. When you issue a request, you are targeting a specific resource where your request will be applied; in this case the test-document (test-document/) resource we previously created and read. By specifying its interaction model, we’re defining how we want this resource to behave.

In Carbon LDP resources can behave as either Documents (RDFSource) or Containers. When you’re editing a document, you want the target resource to behave as a RDFSource.
Because we’re editing properties in a resource, we need it to behave like a Document (RDFSource) as opposed to a Container.

Carbon LDP supports the following interaction model values for the Prefer header:

  • http://www.w3.org/ns/ldp#Container; rel=interaction-model
  • http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model
If-Match

The If-Match header allows you to ensure that the data you are modifying is accurate before changing anything within your document; this is necessary to maintain data consistency. Your application might not be the only one modifying the resource, so the platform needs a way to assure that no data is overridden when executing a request that modifies the resource.

To achieve this Carbon LDP uses ETags, therefore it only allows changes that won’t override each other. In case the ETags do not match, you should first execute a GET request, update your request with the new body and ETag, and retry it.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use the same format used to send the request body. If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json
Body

The body of the request is a graph of triples written in the RDF syntax matching the Content-Type header.

If there is anything from the request body you don’t understand you can check the JSON-LD or TriG W3C specifications, which Carbon LDP complies to.

Since we are issuing a PUT request, it should contain the same properties as the resource currently stored in the platform, along with whichever properties you want to modify. Please note that this includes System Reserved Properties. If these are not contained within the body of your request, or their values differ from the ones on the request body, the platform will send a 412 Precondition Failed response. Alongside, a response body will warn you about trying to modify System Reserved Properties, here you can get an idea of which properties were not maintained in your request.

Therefore, to ensure you have the latest data in your request body, you can execute a GET request before issuing your PUT request.

Issue the PUT request

A successful request will result in HTTP status code 204 No Content.

HTTP Header Value
ETag “1126128674”

As part of the response headers:

  • The ETag header will confirm the time of the document’s modification.

Since we just modified the document, the ETag should be different from the one we used in the If-Match header, as a part of our request.

Using a PATCH request

If you want to modify a resource using a PATCH request, you are changing only certain parts of it. In order to execute this request the server needs to know which document you are modifying, the changes you are applying, and to which properties. To achieve this, Carbon LDP has implemented some methods from the W3C LD PATCH specification. Specifically, the methods implemented by the platform include the Add, Delete, and UpdateList. Let’s see an example where we want to modify a property and include a new type in the test-document we created and read in the previous examples with a PATCH request.

We will modify the ex:literalProperty value from “Example property” to “Modified example property”, and we will add a type ex:PATCHExample to our document. In order to do this we need to implement the Delete and Add methods from the W3C specification to which Carbon LDP complies.

Create the PATCH request

Create the following HTTP request to modify the test-document we have been working with.

PATCH http://localhost:8083/test-document/

HTTP Header Value Required/Optional
Content-Type text/ldpatch Required
Prefer http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model Required
If-Match “1159301007” (latest ETag obtained from the resource) Optional
Accept application/ld+json
or
application/trig
Optional
@prefix rdf:<http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix ex:<http://example.org/ns#> .

Delete {
    <http://localhost:8083/test-document/>
        ex:literalProperty "Example property" .
} .

Add {
    <http://localhost:8083/test-document/>
        ex:literalProperty "Modified example property" ;
        rdf:type ex:PATCHExample .
} .

Review the PATCH request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Content-Type

Since the request method is PATCH it requires a body that details the modifications that will take place in the resource you are targeting. To achieve that, the Content-Type HTTP header tells the platform what kind of content to expect in the body of the request.

In this case, the header is text/ldpatch which is a format developed by the W3C which allows you to describe a set of instructions on how you want to modify certain properties from a resource.

Prefer

The Prefer header uses a link relation to specify the interaction model of the target resource. When you issue a request, you are targeting a specific resource where your request will be applied; in this case the test-document (test-document/)
resource we previously created and read. By specifying its interaction model, we’re defining how we want this resource to behave.

In Carbon LDP resources can behave as either Documents (RDFSource) or Containers. When you’re editing a document, you want the target resource to behave as a RDFSource.
Because we’re editing properties in a resource, we need it to behave like a Document (RDFSource) as opposed to a Container.

Carbon LDP supports the following interaction model values for the Prefer header:

  • http://www.w3.org/ns/ldp#Container; rel=interaction-model
  • http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model
If-Match

The If-Match header allows you to ensure that the data you are modifying is accurate before changing anything within your document; this is necessary to maintain data consistency. Your application might not be the only one modifying the resource, so the platform needs a way to assure that no data is overridden when executing a request that modifies the resource.

To achieve this Carbon LDP uses ETags, therefore it only allows changes that won’t override each other. In case the ETags do not match, you should first execute a GET request, update your request with the new ETag, and retry it.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use the formats that are recommended through this documentation like JSON-LD (application/ld+json) or TriG (application/trig). If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json
Body

The body of a PATCH request includes the statements being modified, as well as the method through which they are being modified. In this case, since we said we wanted to modify the value of the ex:literalProperty, we need to initially delete the current property, and then, include a new property with the new value we want to set. Also, note how you can alter multiple properties with the same method at once.

If there is anything from the request body you don’t understand you can check the LD Patch W3C specification, which Carbon LDP complies to.

Issue the PATCH request

A successful request will result in HTTP status code 204 No Content.

HTTP Header Value
ETag “2035489282”

As part of the response headers:

  • The ETag header will confirm the time of the document’s modification.

Since we just modified the document, the ETag should be different from the one we used in the If-Match header, as a part of our request.

Delete a Document

Issue a DELETE request through HTTP in order to delete the sample document we have been working with.

Create the DELETE request

Create the following HTTP request to delete the test document we have been working with.

DELETE http://localhost:8083/test-document/

HTTP Header Value Required/Optional
Prefer http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model Optional (default is http://www.w3.org/ns/ldp#RDFSource)
If-Match “2035489282” (latest ETag obtained from the resource) Optional
Accept application/ld+json
or
application/trig
Optional

Review the DELETE request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Prefer

The Prefer header uses a link relation to specify the interaction model of the target resource. When you issue a request, you are targeting a specific resource where your request will be applied; in this case the test-document
(test-document/) resource we previously worked with. By specifying its interaction model, we’re defining how we want this resource to behave.

In Carbon LDP resources can behave as either Documents (RDFSource) or Containers. When you’re deleting a document, you want the target resource to interact as a RDFSource.
Because we’re deleting a document, we need it to behave like a Document (RDFSource) as opposed to an Container.
Carbon LDP supports the following interaction model values for the Prefer header:

  • http://www.w3.org/ns/ldp#Container; rel=interaction-model
  • http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model
If-Match

The If-Match header allows you to ensure that the data you are modifying is accurate before changing anything within your document; this is necessary to maintain data consistency. Your application might not be the only one modifying the resource, so the platform needs a way to assure that no data is overridden when executing a request that modifies the resource.

To achieve this Carbon LDP uses ETags, therefore it only allows changes that won’t override each other.
In case the ETags do not match, you should first execute a GET request, update your request with the new body and ETag, and retry it.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use a single format
through all your requests. If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json

Issue the DELETE request

A successful request will result in HTTP status code 204 No Content.

HTTP Header Value
Date Fri, 08 Dec 2017 18:33:17 GMT

As part of the response headers:

  • The Date header will confirm the time when the document got removed from your platform.

Note that your document and every reference to it, will be removed from the platform. Carbon LDP takes care of this, so that with a single request you can completely eliminate a resource from your platform.

The more you know…

When you delete a document that is referenced in one or many lists, Carbon LDP deletes the entries that hold that reference, not just the reference.

Delete all children documents

Create a parent document and create multiple children that are contained by that parent document. You can follow the examples contained in the Postman Collection, in the documents folder.

Now, lets issue a DELETE request through HTTP in order to delete the children documents without affecting the parent one.

Create the DELETE request for all children documents

Create the following HTTP request to delete the parent document we just created.

DELETE http://localhost:8083/parent-document/

HTTP Header Value Required/Optional
Prefer http://www.w3.org/ns/ldp#Container; rel=interaction-model Required
Prefer include=https://carbonldp.com/ns/v1/platform#PreferContainmentResources Required
Prefer omit=https://carbonldp.com/ns/v1/platform#PreferContainer Required
Prefer omit=https://carbonldp.com/ns/v1/platform#PreferMembershipTriples Required
If-Match “2035489282” (latest ETag obtained from the resource) Optional
Accept application/ld+json

or

application/trig

Optional

Review the DELETE request for all children documents

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Prefer

The Prefer header uses a link relation to specify the interaction model of the target resource. When you issue a request, you are targeting a specific resource where your request will be applied; in this case the test-document
(test-document/) resource we previously worked with. By specifying its interaction model, we’re defining how we want this resource to behave.

In Carbon LDP resources can behave as either Documents (RDFSource) or Containers. When you’re deleting a document, you want the target resource to interact as a RDFSource.
Because we’re deleting a document, we need it to behave like a Document (RDFSource) as opposed to a Container.
Carbon LDP supports the following interaction model values for the Prefer header:

  • http://www.w3.org/ns/ldp#Container; rel=interaction-model
  • http://www.w3.org/ns/ldp#RDFSource; rel=interaction-model

Also, Carbon LDP allows the deletion of all the children documents that belong to a container without affecting the parent document. To specify that we only want to affect the container’s children, not the container itself or its members, we need to include the following parameters:

  • include=https://carbonldp.com/ns/v1/platform#PreferContainmentResources
  • omit=https://carbonldp.com/ns/v1/platform#PreferContainer
  • omit=https://carbonldp.com/ns/v1/platform#PreferMembershipTriples

If you are not sure what these preferences mean you can read more about them here.

If-Match

The If-Match header allows you to ensure that the data you are modifying is accurate before changing anything within your document; this is necessary to maintain data consistency. Your application might not be the only one modifying the resource, so the platform needs a way to assure that no data is overridden when executing a request that modifies the resource.

To achieve this Carbon LDP uses ETags, therefore it only allows changes that won’t override each other.
In case the ETags do not match, you should first execute a GET request, update your request with the new body and ETag, and retry it.

Accept

Once your request gets executed by the platform, you might get a response body from the Carbon LDP server. In this case we recommend you define the Accept header to receive this body in a known format; it’s simpler to be consistent and use a single format
through all your requests. If this header is not defined Carbon LDP will send a response in Turtle (text/turtle) by default. Note that Carbon LDP can send response bodies in other formats, such as:

  • JSON-LD: application/ld+json
  • TriG: application/trig
  • RDF XML: application/rdf+xml
  • Binary: application/x-binary-rdf
  • N-Triples: application/n-triples
  • N3: text/n3, text/rdf+n3
  • Trix: application/trix
  • N-Quads: application/n-quads, text/x-nquads, text/nquads
  • JSON-RDF: application/rdf+json

Issue the DELETE request for all children documents

A successful request will result in HTTP status code 204 No Content.

HTTP Header Value
Date Fri, 08 Dec 2017 18:33:17 GMT

As part of the response headers:

  • The Date header will confirm the time when the document got removed from your platform.

Note that the children document and every reference to them, will be removed from the platform. However, the parent document still exists in your platform. Carbon LDP takes care of this, so that with a single request you can completely clean a container in your platform.

The more you know…

The containment triples that refer to the children documents in the parent document will be removed, but this will be the only way in which the parent document will be affected.

Furthermore, if within your request you’re trying to delete documents of type c:RequiredSystemDocument the platform will delete all the possible documents, simply omitting the ones with this particular type.

Conclusion

This guide described how to interact with Carbon LDP documents via the REST API. Normally, developers will prefer use of the Carbon LDP Workbench (GUI) and an SDK, which together simplify the process of building and working with the platform. Still, all functions of the platform can be accessed through the REST API and those developers who understand the REST API may find it advantageous to use in some cases.