-
Notifications
You must be signed in to change notification settings - Fork 20
Resource Management
The primary mechanism for creating, updating and deleting resources is defined by the W3C Linked Data Platform (LDP) specification. For those unfamiliar with LDP, an introductory primer is available.
In brief, all resources can be managed with standard HTTP methods: GET for retrieval, POST for creation, PATCH for modification of RDF resources, PUT for replacing content, DELETE for removing content. In addition HEAD and OPTIONS are very useful for determining the capabilities of a given resource.
RDF-based resources support content negotiation: representations can be requested in text/turtle, application/n-triples and application/ld+json. In addition, an HTML representation is provided for user convenience.
When Non-RDF (binary) resources are added, a corresponding RDF resource is created. Link headers will lead a client to that resource. In general, when an RDF representation is desired, a client should include an Accept header in the request:
Accept: application/ld+json;q=1.0, text/turtle;q=0.5The default representation of a resource will contain user-managed triples, containment triples (if any) and membership triples (if any). By using a Prefer header in the request, it is possible to manipulate which triples to include or exclude from that representation. It is also possible to add categories of triples that are typically excluded from responses, such as audit triples:
Prefer: return=representation; include="http://www.trellisldp.org/ns/trellis#PreferAudit"More information about using Prefer headers can be found in the LDP specification.
When a client creates a resource, it is recommended that the request include a Link header defining the LDP resource type to be created along with the Content-Type of the request:
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type"
Content-Type: application/ld+jsonIn the absence of a Link header, Trellis will guess the LDP resource type based on the Content-Type and/or request body. The default type for RDF-based resources is LDP-RS.
RDF resources can be modified in-place with the HTTP PATCH method. Trellis supports the application/sparql-update content type for this, which is a standards-based mechanism for modifying RDF documents. Binary resources do not allow PATCH on the resource bitstream, but they do allow PATCH for modifying the corresponding RDF description.
When modifying an existing resource with PUT, it is recommended that a client use an If-Match header along with the ETag identifier for the resource. Note: the supplied ETag value must be a strong ETag, even if the resource generally responds with a weak ETag value.
It is possible to modify the LDP Resource type with PUT so long as the new type is a subtype of the existing resource. To do this, an appropriate Link header would need to be supplied. Trellis will respond with an error if the new LDP type is not a subtype of the existing resource.
It is also possible to create resources with PUT. Doing so, however, will lead to a disconnected graph of resources, as any intermediate containers will not be generated automatically. If a client wishes to avoid this situation, the client should use only POST for resource creation.
A resource can be deleted with the HTTP DELETE method. It is worth noting that recursive deletes are not supported, and so a DELETE operation on a resource that contains child resources will result in the deletion of the target resource but no change to the child resources. This can lead to a disconnected graph of resources, and so a client wishing to avoid this possibility will need to first walk the resource hierarchy before deleting resources. It is also recommended to first manipulate the ACL resources of the resources in the hierarchy, preventing any modification while the DELETE is in-flight.
It is also worth noting that a DELETE operation does not remove historic versions of a resource.