Version: 1.0
Last modified: 2010-12-23 10:02:06EST

RUcore Relationship API Documentation

API Methods

GET Relationship Method
Provides relationships stored within a given object
ADD Relationship Method
Creates relationship(s) between resources
DELETE Relationship Method
Deletes relationship(s) associated with resources
DESCRIBE Relationship Method
Provides an RDF document of all supported registered ontologies

Method - GET Relationship

Provides relationships stored within a given object

HTTP Method

GET

Base Request URL

http://rucore.libraries.rutgers.edu/api/relationship/get/

Request URL Pattern

http://rucore.libraries.rutgers.edu/api/relationship/get/{Parameter1}/{Parameter2}/{Parameter3}/

Request Parameters

Parameter	Value	Description
1	string (required) rutgers-lib:{numeric value} The above namespace needs to be followed by a valid numeric object ID.	A full object ID containing the namespace mentioned must be provided. If an invalid ID is submitted nothing will be returned.
2	string (optional)	As an option you can pass a predicate or base ontology, this will limit the results returned to only those ontologies.
3	string (optional) xml/ Resulting data is formatted in XML and returned with mime-type: application/xml json/ Resulting data is formatted in JSON and returned with mime-type: application/json php/ Resulting data is formatted in serialized PHP and returned with mime-type: application/x-httpd-php rdf/ Resulting data is formatted in RDF and returned with mime-type: application/xml. Note additional attributes mentioned below are not returned when requesting for data in RDF format.	This value is optional and controls the format of the resulting list. Current default is xml.

Sample Request - for accessing all relationships for the object rutgers-lib:24827

http://rucore.libraries.rutgers.edu/api/relationship/get/rutgers-lib:24827/

Sample Request - for accessing all Analytic(hasAnalytic/isAnalyticOf) relationships for the object rutgers-lib:24827

http://rucore.libraries.rutgers.edu/api/relationship/get/rutgers-lib:24827/analytic/

Sample Request - for accessing all hasAnalytic relationships for the object rutgers-lib:24827

http://rucore.libraries.rutgers.edu/api/relationship/get/rutgers-lib:24827/hasAnalytic/

Sample Request - for accessing all relationships for the object rutgers-lib:24827 in JSON. Note an empty predicate is allowable.

http://rucore.libraries.rutgers.edu/api/relationship/get/rutgers-lib:24827//json/

Sample output in XML format

In this example above the root element <relationships> contains the attributes ID, determined by the request, and the RESULTS, number of relationships found. One or many <relationship> elements might appear, it is dependent on the number of relationships found for the object being requested.

Each <relationship> has a series of ATTRIBUTES explained below:

@POSITIONStores current entries position in the list.
@INDEXBoolean value; TRUE or FALSE. Used as an indicator to determine whether the relationships object should be included in the subjects index at time of index creation.
@FOLLOWBoolean value; TRUE or FALSE. Used as an indicator to determine whether the relationships object should be mentioned when viewing the subject in a results display.
@DELETEBoolean value; TRUE or FALSE. Used as an indicator to determine whether the relationships object should be deleted/purged if the subject is being deleted/purged.
@RECURSEBoolean value; TRUE or FALSE. Used as an indicator to determine whether the relationships object should be followed recursively when indexing the subject.

The subelements that appear in <relationship> are as follows:

<subject>The subject of the relationship, usually the ID of what was requested
<predicate>The predicate/ontology that relates the subject to the object
<object>The object of the relationship, what the subject relates to. Can be a local system ID or a URI. See <isLiteral> for more information.
<isLiteral>A boolean value, true(1) or false(0). Indicates if the object is a local resource (true) or a URI (false), external resource.
<datatype>Datatype of the literal, currently not used.

Method - ADD Relationship (restricted use)

Creates relationship(s) between resources

HTTP Method

POST

HTTP Response

200 on success; 400 with error code on failure

Base Request URL

http://rucore.libraries.rutgers.edu/api/relationship/

Request Parameters

Parameter	Value	Description
key	string (required)	The ADD method is a restricted use method meaning a valid key must be submitted with every request. If you are interested in obtaining a key contact us.
do	string (required) add	The action that is to be performed by the API.
subject	string (required) rutgers-lib:{numeric value} The above namespace needs to be followed by a valid numeric object ID.	This is the subject for the relationship being created
predicate	string (required)	Registered ontology, see the DESCRIBE method for more information.
object	string (required) rutgers-lib:{numeric value} The above namespace needs to be followed by a valid numeric object ID. {uri} A valid URI of a resource	The object used when creating the relationship.
type	string (optional) single	Providing this parameter with value single only the predicate ontology relationship will be created in the subject. A relationship using the predicate provided will be created between the subject and object; however the corresponding relationship between the object and the subject will not automatically be created.

Sample Request - creating both relationships between rutgers-lib:24827 and rutgers-lib:25566 using the predicate hasAnalytic

Sample code in PHP to perform request

Using the above sample code and request the following is performed.

rutgers-lib:24827
Subject

-----hasAnalytic----->

<-----isAnalyticOf-----

rutgers-lib:25566
Object

You will notice in this example two relationships are actually created; hasAnalytic and isAnalyticOf. This is because the predicate supplied, hasAnalytic has a corresponding ontology registered in the system which is used to automatically create the corresponding relationship. The relationship is fully defined in both the subject and object resources. If either relationship already existed they would not be recreated.

Sample Request - creating a single relationship between rutgers-lib:24827 and rutgers-lib:25566 using the predicate hasAnalytic

Sample code in PHP to perform request

Using the above sample code and request the following is performed.

rutgers-lib:24827
Subject

-----hasAnalytic----->

rutgers-lib:25566
Object

In this example only one relationship is created, hasAnalytic. This is because type=single was supplied. In this case the subject has a relationship established to the object, however the object knows nothing of its relationship to the subject. This creates issues because the relationship is not fully defined. A separate request would need to be made using the isAnalyticOf and switching the subject and object values.

This is highly discouraged because of the additional steps taken and the likelihood relationships might not be fully expressed with both the subject and object. It is strongly suggested that relationships are not created using type=single.

Method - DELETE Relationship (restricted use)

Deletes relationship(s) associated with resources

HTTP Method

DELETE

HTTP Response

204 on success; 400 with error code on failure

Base Request URL

http://rucore.libraries.rutgers.edu/api/relationship/

Request Parameters

Parameter	Value	Description
key	string (required)	The DELETE method is a restricted use method meaning a valid key must be submitted with every request. If you are interested in obtaining a key contact us.
do	string (required) delete	The action that is to be performed by the API.
subject	string (required) rutgers-lib:{numeric value} The above namespace needs to be followed by a valid numeric object ID.	This is the subject for the relationship being deleted
predicate	string (optional)	Registered ontology, see the DESCRIBE method for more information. When supplied only relationships using this ontology are deleted. If no predicate is supplied then all registered ontologies are deleted from the subject.
object	string (optional) rutgers-lib:{numeric value} The above namespace needs to be followed by a valid numeric object ID. {uri} A valid URI of a resource	When supplied only relationships between the subject and the object are deleted.
type	string (optional) single	Providing this parameter with value single only the predicate ontology relationship will be deleted from the subject. If a relationship is expressed in the object between the object and the subject this will not be automatically deleted.

Sample Request - deleting all relationships for rutgers-lib:24827

Sample code in PHP to perform request

Using the above sample code all registered ontology relationships will be deleted from the subject. Also, the corresponding ontology relationships will be deleted from the related objects.

Sample Request - deleting all relationships for rutgers-lib:24827 using the predicate hasAnalytic

Sample code in PHP to perform request

Using the above sample code all hasAnalytic ontology relationships will be deleted from the subject. Also, the corresponding ontology relationship isAnalyticOf will be deleted from the related objects.

Sample Request - deleting all relationships between rutgers-lib:24827 and rutgers-lib:25566

Sample code in PHP to perform request

Using the above sample code all registered ontology relationships will be deleted between the subject and the object from both the subject and the object.

Sample Request - deleting relationships between rutgers-lib:24827 and rutgers-lib:25566 using the predicate hasAnalytic

Sample code in PHP to perform request

Using the above sample code the hasAnalytic ontology relationship between rutgers-lib:24827 and rutgers-lib:25566 will be deleted. Also, the corresponding ontology relationship isAnalyticOf between rutgers-lib:25566 and rutgers-lib:24827 will be deleted.

Sample Request - deleting a single relationship between rutgers-lib:24827 and rutgers-lib:25566 using the predicate hasAnalytic

Sample code in PHP to perform request

Using the above sample code the hasAnalytic ontology relationship between rutgers-lib:24827 and rutgers-lib:25566 will be deleted. The corresponding ontology relationship isAnalyticOf between rutgers-lib:25566 and rutgers-lib:24827 will NOT be deleted.

This is highly discouraged because it leads to the likelihood that relationships will not be fully expressed. It is strongly suggested that relationships are not deleted using type=single.

Method - DESCRIBE Relationship

Provides an RDF document of all supported registered ontologies

HTTP Method

GET

Base Request URL

http://rucore.libraries.rutgers.edu/api/relationship/describe/

Sample Request - for accessing all registered ontologies

http://rucore.libraries.rutgers.edu/api/relationship/describe/

Sample output

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">
 <rdfs:Class rdf:ID="Analytic">
  <rdfs:label>Analytic Relationship</rdfs:label>
  <rdfs:comment>Used to describe the relationship between a analytic resource and a content resource.</rdfs:comment>
 </rdfs:Class>
 <rdf:Property rdf:ID="hasAnalytic">
  <rdfs:label>Has Analytic</rdfs:label>
  <rdfs:comment>Describes the relationship between a analytic resource and a content resource.</rdfs:comment>
  <rdfs:range rdf:resource="http://www.w3.org/2000/01/rdf-schema#Literal"/>
  <rdfs:domain rdf:resource="#Analytic"/>
 </rdf:Property>
 <rdf:Property rdf:ID="isAnalyticOf">
  <rdfs:label>Is Analytic Of</rdfs:label>
  <rdfs:comment>Describes the relationship between a content resource and a analytic resource.</rdfs:comment>
  <rdfs:range rdf:resource="http://www.w3.org/2000/01/rdf-schema#Literal"/>
  <rdfs:domain rdf:resource="#Analytic"/>
 </rdf:Property>
...
</rdf:RDF>

Using the RDF document above one could build a dynamic list of registered ontologies the system recognizes. This dynamic list could be used when managing relationships through a user interface.

Sample code in PHP create a dynamic list of registered ontologies.

<?php
//create DOM, load file and save as a string
$rdfDOM = new DOMDocument();
$rdfDOM->load('http://rucore.libraries.rutgers.edu/api/relationship/describe/');
$rdfString = $rdfDOM->saveXML();
unset($rdfDOM);

//strip out namespaces and load into simpleXML object
$ns = array("rdf:", "rdfs:");
$rdfString = str_replace($ns, "", $rdfString);
$rdfXML = simplexml_load_string($rdfString);
unset($ns, $rdfString);

//process object and store array of classes and properties
$arrRDF = array();
//create class arrays
foreach ($rdfXML->Class as $class) {
   $arrRDF[(string)$class->attributes()->ID] = array();
   $arrRDF[(string)$class->attributes()->ID]['label'] = (string)$class->label;
}//END foreach class
//add property information to class arrays
foreach ($rdfXML->Property as $property) {
   $arrRDF[str_replace("#", "", (string)$property->domain->attributes()->resource)]['properties'][(string)$property->attributes()->ID] = (string)$property->label;
}
unset($rdfXML, $class, $property);

//output menu list
echo "<select name=\"predicate\">\n";
foreach($arrRDF as $class => $properties) {
   echo "\t<optgroup label=\"" . $properties['label'] . "\">\n";
   foreach ($properties['properties'] as $property => $label) {
      echo "\t<option value=\"" . $property. "\">--" . $label . "</option>\n";
   }//END foreach property
   echo "\t</optgroup>\n";
}//END foreach class
echo "</select>\n";
unset($arrRDF, $class, $properties, $property);
?>