RUcore - Relationship Service

RUcore: Rutgers University Community Repository

Search
- All
- Text
- Images
- Audio
- Video
Advanced Search | Help

Search all content in all RUcore collections.
Services
Collections

Help Contact Us My Account

Home

Web Services/APIs separator

Relationship Service

About

The Relationship service provides methods for retrieving, creating, deleting, and describing relationship statements in RUcore.

The base URL for our Relationship service is

Responses

Responses can be formed in XML, JSON, serialized PHP, or RDF depending on the method being used. Further detail can be found under each methods documentation.

Methods

Get Relationships
Add Relationships
Delete Relationships
Describe Relationships

Get

Top

Provides relationships stored within a given object

HTTP Method

GET

URI

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

Request URL Pattern

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

Arguments

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

https://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

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

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

https://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.

https://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.

Add

Top

Creates relationship(s) between resources

HTTP Method

POST

URI

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

Restricted

Authorization key required

HTTP Response

200 on success; 400 with error code on failure

Arguments

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.

Delete

Top

Deletes relationship(s) associated with resources

HTTP Method

DELETE

URI

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

Restricted

Authorization key required

HTTP Response

204 on success; 400 with error code on failure

Arguments

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.

Describe

Top

Provides an RDF document of all supported registered ontologies

HTTP Method

GET

URI

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

Sample Request - for accessing all registered ontologies

https://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('https://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);
?>

Sample output

Background

RUcore has been developing web services that allow software applications to easily interact with our repository framework of services. These web services are REST based and typically respond to requests in XML or JSON.

Web Services

International Image Interoperability Framework(IIIF) Service - Provides scholars uniform and rich access to image-based resources in RUcore.
Manage Service - This service provides methods to create resource in RUcore.
Open Archives Initiative - Protocol for Metadata Harvesting - Use the Open Archives Initiative Protocol for Metadata Harvesting to access resources in RUcore.
Persistent Uniform Resource Locator Service - This service provides methods to create, update, and manage PURLs.
Relationship Service - This service provides methods for retrieving, creating, deleting, and describing relationship statements in RUcore.
Search Service - This service provides methods for querying for resoruces in RUcore.

Listserv and Google Group

A listserv has been established that will be used to communicate service outages and RUcore web service related news. The listserv address is rucore_web_services[at]email.rutgers.edu. Visit this page to subscribe.

A Google Group has been created to provide a place for discussion about the web services RUcore provides.

If you have any further questions please contact us.

Version 8.5.5