Relationship Service
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
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.
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

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.2.5
Rutgers University Libraries - Copyright ©2017