• Collaboration & E-Learning
• Virtual Project Work
• Online Lectures
• Virtual Meetings
• Digital Learning Library
  • About SWITCHcollection
  • Architecture
  • Documents
  • Evaluation
  • Metadata and Model
  • Specification
    • 1. Collections
    • 2. Object Model
    • 3. Access Policy
    • 4. Web API
    • 5. LMS Integration
    • 6. REST API
    • 7. Harvesting
  • Related Projects
  • Help
  • Events
  • Conditions
  • About OER
  • Contact
• E-learning Community
• Send an SMS/Fax

6. REST Interface - API

The API documented in this section follows the REST principle which is explained here: Wikipedia , Give it a REST.

The REST API is based on the implementation of the SOAP Interface in PHP (LORapi) from Fedora. The REST API of Fedora 2 can't be used directly because some crucial function like ingest or modifyDatastream are not available.

The REST interface is not shibbolised. Only GET-requests are open to the public. POST-, PUT- and DELETE-requests are restricted to registered 3rd-party Applications.

6.1. GET Request

https://collection.switch.ch/LOREST/collections
Function: Returns all folders existing in SWITCHcollection

https://collection.switch.ch/LOREST/collections/collectionID
Function: Returns all subfolders of the folder with the given ID

https://collection.switch.ch/LOREST/collections/collectionID/objects
Function: Returns all objects of the folder with the given ID

https://collection.switch.ch/LOREST/objects/objectID
Function: Returns the metadata of the object with the given ID

https://collection.switch.ch/LOREST/objects/objectID/datastreams
Function: Returns a list the datastreams of the objects with the given ID

https://collection.switch.ch/LOREST/objects/objectID/datastreams/datastreamID
Function: Returns the metadata of the datastream with the given ID

https://collection.switch.ch/LOREST/objects/find?query=searchTerm&searchLevel=1&hitPageSize=hitPageSize&hitPageStart=hitPageStart&sortFields=sortOrder
query (requried): String. The word or phrase you are looking for. See Lucene Site for more information. http://lucene.apache.org/java/2_4_1/queryparsersyntax.html
searchLevel (optional): Integer. 1 = exact search for the searchTerm. 2 = adds a wildcard (*) at the end of the searchTerm. 3 = adds a Tilde(~) for Fuzzy search at the end of the searchTerm. If no searchLevel is given, Collection search best effort, which meens it tries the next higher searchLevel if no result is found on the lower.
hitPageSize (optional): How many results should be returned per Page. Default is 1000
hitPageStart (optional): At wich result the results shhould start displaing.
sortFields (optional): Sort order. Default ist by relevance (PID,SCORE,false). You can also sort by Title (fgs.label,STRING,false;PID,SCORE), Date (fgs.lastModifiedDate,AUTO,true;PID,SCORE) or Author (chor_dcterms.creatorSorted,STRING,false;PID,SCORE). To change the sort direction, toggle the false to true and vice versa.

https://collection.switch.ch/LOREST/collections/findSwitchCastChannels?institution=institution
Returns the PID of the SWITCHcast Folder in Collection for the given institution.
institution: the domain name of the institution (without www) eg.: uzh.ch or hslu.ch
 

6.2. POST Request

General: All POST-requests need a userID (=AAI-ID) and a POST parameter with the name 'POSTparameter'. This Parameter is an XML-String which contains the necessary data. An example of such an XML-String is shown for each of the different POST URLs.

https://collection.switch.ch/LOREST/users/userID/collections/collectionID
Function: Creates a new folder in the folder with the given ID.
Example XML:
<?xml version="1.0" encoding="UTF-8"?>
<object>
  <contentModel>basiccollection</contentModel>
  <CHOR_DC>
    <title>A Test Collection</title>
    <creator>Albert Einstein</creator>
    <aaiid>604369@switch.ch</aaiid>
    <accessRights access="public"></accessRights>
    <rights access="institution">switch.ch</rights>
  </CHOR_DC>
</object>

https://collection.switch.ch/LOREST/users/userID/collections/collectionID/objects
Function: Creates a new object in the folder with the given ID.
Example XML:
<?xml version="1.0" encoding="UTF-8"?>
<object>
  <contentModel>basiccollection</contentModel>
  <CHOR_DC>
    <title>A Test Object</title>
    <creator>Albert Einstein</creator>
    <aaiid>604369@switch.ch</aaiid>
    <accessRights access="public"></accessRights>
    <rights access="institution">switch.ch</rights>
    <license>http://creativecommons.org/licenses/by-nc-nd/2.5/ch/</license>
    <publisher>SWITCH</publisher>
    <rightsHolder>A.E.</rightsHolder>
    <alternative>An alternative Title</alternative>
    <tableOfContents>
      Chapter 1 - The Beginning
      Chapter 2 - The End
    </tableOfContents>
    <discipline>5214</discipline>
    <abstract>
      This is an Object.
      Not two or three.
    </abstract>
    <subject>A Keyword</subject>
    <subject>Another Keyword</subject>
    <description>This was written in Zurich</description>
    <issued>06.10.2008</issued>
    <type>MovingImage</type>
    <extent>2 min</extent>
    <bibliographicCitation>Lorum ipsum</bibliographicCitation>
    <language>deu</language>
    <educationLevel>Level</educationLevel>
    <instructionalMethod>Picture</instructionalMethod>
    <source>mySpecID_001</source>
  </CHOR_DC>
  <DS>
    <dsLocation>http://download.blender.org/documentation/htmlI/PartM/mesh_modeling_A/gfx/Smooth7.png</dsLocation>
    <dsLabel>A Testobject</dsLabel>
    <controlGroup>M</controlGroup>
    <MIMEType>image/png</MIMEType>
    <formatURI></formatURI>
  </DS>
  <THUMBNAIL>
    <dsLocation>http://www.3dm3.com/tutorials/scripted_utiliy/Fig-3-ObjectWithConeandBox.jpg</dsLocation>
    <dsLabel>Thumbnail for the Testobjcet</dsLabel>
    <controlGroup>E</controlGroup>
    <MIMEType>image/jpg</MIMEType>
    <formatURI></formatURI>
  </THUMBNAIL>
</object>

https://collection.switch.ch/LOREST/users/userID/objects/objectID/datastreams
Function: Creates a new datastream in the object with the given ID.
Example XML:
<?xml version="1.0" encoding="UTF-8"?>
<object>
  <DS>
    <dsLocation>http://download.blender.org/documentation/htmlI/PartM/mesh_modeling_A/gfx/Smooth1.png</dsLocation>
    <dsLabel>A Testobject</dsLabel>
    <controlGroup>M</controlGroup>
    <MIMEType>image/png</MIMEType>
    <formatURI></formatURI>
  </DS>
</object>

6.3.    PUT

General: All PUT-requests need a userID (=AAI-ID) and a PUT parameter. This Parameter is the same XML-String used in the POST section.

https://collection.switch.ch/LOREST/users/userID/collections/collectionID
Function:Updates the folder with the given ID.

https://collection.switch.ch/LOREST/users/userID/objects/objectID
Function: Updates the object with the given ID.

https://collection.switch.ch/LOREST/users/userID/objects/objectID/datastreams/datastreamID
Function: Updates the datastream with the given datastream ID in the object with the given ID.

6.4.    DELETE

General: All DELETE-requests need a userID (=AAI-ID).

https://collection.switch.ch/LOREST/users/userID/collections/collectionID
Function: Deletes the folder with the given ID.

https://collection.switch.ch/LOREST/users/userID/objects/objectID/
Function: Deletes the object with the given ID.

https://collection.switch.ch/LOREST/users/userID/objects/objectID/datastreams/datastreamID
Function: Deletes the datastream in the object with the given ID.