Object model

The REST API object model provides a summary of the various types of resources you can manage and interact with using REST.

Object Model

The following diagram depicts the all of the objects you can manage and interact with using REST. All objects are RDF resources. You can think of them as RDF documents which, once created, are identified by a URI. You can create, update, read, and delete these objects by issuing HTTP requests to the URI of the resource or its parent container (e.g. POST, PUT, GET, DELETE). There are also other types of RESTful operations that each object might expose depending on the type of the object. The object hierarchy depicts how certain objects extend others and thus would have the same RESTful operations or behavior as the parent type.

Object Descriptions

Following is a brief description for each of the objects, listed in alphabetical order.

AccessPoint

An AccessPoint is a class of container that can manage member resources stored in another container other than itself. Both DirectContainer and IndirectContainer are of this class. However, since the IndirectContainer is not yet implemented in Carbon, the AccessPoint can be regarded as equivalent to DirectContainer. An AccessPoint is useful when you want to manage more than one list of members for more than one given property on a resource. To understand how this is useful, consider the BasicContainer in contrast. A BasicContainer stores its members in itself, but is limited to managing only one list of members by one single property (e.g. ex:hasChildren). If you need multiple membership properties on a container, each managing a kind of membership to the resource (and where the members may not exist within the container itself), the AccessPoint can help. Imagine a BlogPost resource, for example. With an AccessPoint, you could define properties like ex:commentex:tagex:like all on the same BlogPost resource with each property managing one or more members. The comments or tag resources may be stored in child comments and tags containers, but they are managed and enumerated by the parent BlogPost container.

AccessControlList

A configuration resource that defines the security access control for a given resource. An AccessControlList controls access to a resource by defining what permissions one or more given roles have on the resource. The ACL defines an accessControlEntry and an inheritableEntry – each linking to an AccessControlEntry by way of a blank nodes. The entry linked by accessControlEntry defines access to the resource itself. The entry linked by inheritableEntry defines permissions that can be inherited by child resources when the child resources do not override them.

Agent

An RDFSource document that represents a user or system account that can authenticate with the Carbon platform or a Carbon application.

Application

An RDSource document that represents an application in the Carbon platform. In order to create a new Carbon application, you must post an Application RDFSource document. Doing so creates the root container for your new application, under which you can begin posting application-specific resources.

AppRole

An RDFSource document that is used to control access to application resources. An AppRole defines what kind of access a group of agents have on one or more resources. An AppRole is defined by the rdf:type of https://carbonldp.com/ns/v1/security#AppRole (or cs:AppRole, for short).

Backup

An RDFRepresentation that describes the zip archive created by an ExportBackup job; it contains information such as the archive’s format, size, and cretaion time, for example.

BasicContainer

An LDP Container whose members are stored within itself. In a BasicContainer, the property ldp:contains defines a set of triples, maintained by the container, which are documents created by the container. In LDP terminology, these are called “containment triples” and they always bear the triple form of: <Container URI> <ldp:contains> <Document URI> Basic Containers provide the most straight-forward way to have generic storage in Carbon and for creating a containment hierarchy of arbitrary resources.

Container

As the name implies, LDP Containers contains things. They don’t actually literally contain resources, but rather – they contain links pointing to other resources. Basically, they represent collections. A container responds to client requests for creation, modification, and/or enumeration of its linked members. In other words, the URI that identifies a given container acts as an HTTP interaction point through which members and membership can be managed. A container is also an RDFSource, so while it has a special function as a membership controller, it may also represent additional data that is valuable to the clients that access it. In other words, you can interact with a Container as both a membership controller and as an RDFSource document. The behavior depends upon the interaction model defined as part of your request. There are three different types of LDP containers, each with variant uses and capabilities, and described by one of the three container types with rdf:type of ldp:BasicContainerldp:DirectContainer, or ldp:IndirectContainer. See also: Linked Data Platform Containers [LDP]

DirectContainer

See AccessPoint

Execution

A resource that represents the execution of a Job and contains information about the job’s execution such as the start time, end time, state of the job’s execution, and, for certain types of jobs, where the results of the job execution are stored.

ExportBackupJob

A type of Job that, when executed, will export the data of a Carbon application for backup purposes or for importing into another server. When an ExportBackup job is executed, it creates a zip archive file inside of which can be found a *.trig file that has all the application data (e.g. triples), and a folder containing all of the application’s NonRDFSource resources such as images and files. The archive produced by an ExportBackup can be subsequently imported with an ImportBackup job.

ImportBackupJob

A type of Job that, when executed, will replace a Carbon application’s resources with the resources created by an ExportBackup job.

ImportLDAPAgentsJob

A type of Job that, when executed, creates LDAPAgents that contain properties that can be used as credentials for authentication. This Job can be configured so only certain user properties are copied from the LDAP server when the representative LDAPAgent is created.

IndirectContainer

Though defined in the W3C Linked Data Platform 1.0 specification [LDP], IndirectContainers are not yet supported by Carbon.

Job

A Job is a resource that defines one or more specialized tasks to be executed on the server. A Job may be scheduled or configured to run on demand. Each time the job runs, an Execution document is created with information about the job’s execution.

LDAPAgent

A special type of Agent that is created based on the information retrieved from an LDAP server when an ImportLDAPAgentsJob is executed.

LDAPServer

An LDP RDFSource that contains the required configuration information to connect to an LDAP server.

RDFRepresentation

An RDFRepresentation is an RDFSource that contains meta-data (properties) about a Non-RDFSource (a file or binary). When a file is uploaded into a Carbon app or otherwise created by Carbon, the RDFRepresentation is also created to describe and store various information about the file.

RDFSource

A resource (basically, a document in Carbon) whose state is fully represented in RDF. An RDFSource is identified by a URI, which can be used with HTTP requests (GET, PUT, POST, DELETE). The content of an RDFSource document is an RDF graph – a set of RDF triples. The triples are the data properties of the resource, which can be either literal properties (string, date, number, etc.) or object properties (links to other resource URIs). All resources you create within a Carbon application, with the exception of ACLs, are RDFSource documents. That is to say, they are described by the rdf:typeof http://www.w3.org/ns/ldp#RDFSource, even if also described by additional types such as those that define the object classes of your application.

See also:

 

References

[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. W3C. Linked Data Platform 1.0. 26 February 2015. W3C Recommendation. URL: http://www.w3.org/TR/ldp/