OICS Middle Layer API documentation

The OICS Middle Layer tries to bundle the functionality needed for implementation of the ICOPER user cases into a coherent API that is accessible from all systems and tools inside and outside the consortium. Its key focus is the integration of concepts and data related to key processes in outcome-based education. The OICS provides a backbone for enabling the testing of feasibility and utility of these processes for different stakeholders. The OICS Middle Layer defines the interface between OICS and parties interested in accessing OICS content, while the harvesting infrastructure based on OAI-PMH constitutes the interface to content providers.

The Middle Layer provides method definitions that are easier to adopt than the interfaces defined by the SQI and SPI protocols implemented in the OICS backend. Middle layer implementations can call upon these backend protocols and give clients access to their functionality through simpler wrapper methods.

This document serves as reference for the version 1.0 of the OICS Middle layer.

This API defines abstract services that can be bound to different standards for data formats and protocols. Bindings are explained in Bindings.

Authentication and authorization is out of scope for the Middle layer API and needs to be defined on the level of the binding. But it is assumed that services are consumed by authenticated users and that policies define access rights and deal with privacy protection and security concerns.

This API includes the following services:

• User management and learning outcome profile service
• Recommendation service
• Search and retrieval service
• Publication service

Following the e-Framework, we provide for each service a service description, enumerate the functionalities it provides, and state the business objects it is operating on.

Currently three partial implementations of the OICS Middle layer API have been developed. The rationale for this strategy is to prove the concept of an abstract service definition that can be bound to specific result formats and communication protocols, and to evaluate their respective usability from the perspective of an application developer.

ATOM implementation

This implementation binds the methods defined in the Middle layer API to a REST interface as defined by the ATOM syndication format and the SPI standard in its AtomPub binding: A collection of resources is mapped to an ATOM feed, a resource corresponds to an entry, and metadata is described in an entry document. Feeds, entries and entry documents are retrieved and manipulated through the basic commands of the HTTP protocol. Authentication is handled through HTTP Basic Authentication.

We explain the design of this binding for each part of the Middle layer. The base URI for the implementation is http://oics.icoper.org. All URIs mentioned below are relative to this base URI.

Detailed examples of how to call the services provided by this implementation can be found as part of the ICOPER online training as well as in the online version of the Middle layer documentation.

User management, learning outcome profile and recommendation services

The service URI is mapped to /icoper-user-service . Users are represented by XML documents listing available properties.

Table 1: ATOM binding of user management service

Search and retrieval service

In the current version of the OICS, there are three repositories:

• learning outcome definitions,
• learning resources (instructional designs and learning content),
• learning opportunities.

For each of these, an ATOM feed lists the content. Filter expressions can be used to list only resources of a certain learning resource type (teaching method, learning design, assessment resources). ATOM URIs for these types are also defined as aliases for the specific filter expressions.

For each repository, there is a service document that lists the available collections. See below the description of the publication service for these. Each collection has its own ATOM feed, to which the same filter expressions can be applied.

The following GET parameters are interpreted:

• query: if no filter is defined, a full text query is performed
• filter: the filter can be used to restrict the query to particular fields in the LOM structure, referenced in the following syntax: “{category}.{name}”. For categories whose size is greater than 1, you can filter the whole category with a filter called “{category}”. For example, valid values for filter are
  • general.title
  • lifeCycle.contribute
  • technical.format
  • educational.learningOutcome
  • rights.cost
  • relation
  • annotation
  • classification

Those filters query the information explicitly stored in the respective fields, i.e. for example for learning outcomes and relations, the identifier of the linked resource. Additionally, there exist specialized filters that cache textual information about the linked resource, or provide more efficient access to frequently needed information:

• • IcoperLearningOutcome: filter based on title and description of linked learning outcome
  • IcoperRelationUses: filter based on full text index of used resource
  • IcoperRelationImplements: filters based on full text index of implemented teaching methods
  • IcoperClassificationCSO-FoE: filters based on values from the CSO-FoE taxonomy
• page_size
• page_number
• filter_expression: by providing this parameter multiple times, filter expressions can be combined. Each expression has the following syntax {filter=query}, e.g.: ?filter_expression=general.description=film&filter_expression=general.title=literature

Following the Atom publishing protocol (AtomPub 2007) there are three links in each ATOM entry:

• Without rel attribute: This link points at the location of the object in the OICS.
• Rel=edit: This link points at an ATOM representation of the object; it can be used to change the metadata for the object, or to submit annotations.
• Rel=edit-media: Through this link (whose URI is identical with the first link in the current implementation) the object itself can be edited.

Table 3: ATOM binding of search and retrieval services

Publication service

Publication service is provided through an implementation of the SWORD/AtomPub binding of SPI (Ternier 2009). The Simple Webservice Offering Repository Deposit (SWORD) (SWORD 2010) is a profile of the Atom Publishing Protocol (AtomPub) (AtomPub 2007) that provides a REST style API for creating web resources. This binding introduces a metadata element in the namespace “http://www.cenorm.be/xsd/SPI” that wraps a resource’s metadata record.

The repositories for learning resources (instructional models and learning content), and for learning outcome definitions have each a service document that lists the available collections (for each content provider). Each repository has a global ATOM feed for retrieving and searching objects across the whole repository.

Table 4: URIs for OICS repositories

The "accept" element inside each collection element lists the content types that can be posted to it. If it is empty, the user retrieving the service document is not allowed to submit content of any type.

Table 5: ATOM binding for publication service

Publishing learning opportunities

The XML binding of the MLO specification groups three different types of objects (providers, specifications and instances) into one XML document. In order to support this binding, the SPI target for the MLO repository, is invoked in a slightly different way: There is no service document, new providers (together with embedded specifications and instances are directly POSTed to the repository’s ATOM URI). Updating of a provider (adding new specifications and instances) can be achieved either by PUTting a new document to the provider’s edit link, or by rePOSTing the document to the repository’s ATOM URI.

JSON implementation

This implementation has been built on top of the ARIADNE Repository services, which provides us with (i) an SQI interface for searching the OICS which enables us to work with different kinds of query languages and different types of result sets, and (ii) with an SPI interface for publishing new or changed material into the OICS. Complete details about the ARIADNE repository infrastructure can be found in (Ternier et.al, 2009).

The search and retrieval services of the OICS middle layer API have been deployed on top of the ARIADNE infrastructure. These services use a REST interface and provide the results to the client tools in the JavaScript Object Notation (JSON, 2006) data format. JSON is a lightweight data format heavily used by web developers due to its simplicity compared to the traditional XML data format approaches.

ICOPERs’ JSON implementation of the OICS middle layer currently contains the following methods:

• getLearningOutcomes
• getTeachingMethods
• getLearningDesigns
• getLearningContent
• getAssessmentDesigns
• getAssessmentResources
• getAssessmentMethods
• getMetadata

These methods receive a (i) query, (ii) page number and (iii) page size parameters. For example, we can issue a query with the following GET request:

getLearningOutcomes?q=genes&pn=1&ps=1

The result will only be the identifier of the first result on the first page from the LOD instances that fulfils the query.

{ "results" [

{ "id" : "01914f8eac35d7e14afa065217edd8c0" , "title":"genes"}

]

}

The implemented method for retrieval of a metadata record is called getMetadata. This method receives the object identifier as a parameter. It returns the full metadata instance if the given identifier is valid. For example, we can retrieve an object by this request:

getMetadata?objId= oai:test1.km.co.at:skolverket_8863

The result will return the metadata instance of the requested identifier, for example:

{ "results" [

{ "id" : "oai:test1.km.co.at:skolverket_8863" , "md":"<lom> .... </lom>"}

]

}

The live services are located at http://ariadne.cs.kuleuven.be/icoper-ws/api/icoper/

The development URL is http://ariadne.cs.kuleuven.be/icoper-dev-ws/api/icoper/

The methods offered by the implementations are summarized in the following table.

Table 6: JSON binding for search and retrieval service

PLQL –SQI Wrapper

This implementation is a wrapper around the underlying SQI implementation of the ARIADNE repository.

Its URI is http://oics.icoper.org/client/api/search.php

It interprets the following GET parameters:

• q: can be a PLQL expression, or a list of keywords from which a PLQL expression is constructed
• lang (can also be provided through the HTTP_ACCEPT_LANGUAGE request header): selects the language of the returned data for those resource attributes that are available in multiple languages. If no lang is provided, the first string in the resource LOM will be selected
• format: if set to extended, information about the resource’s identifiers are included

The result format is a simple XML document:

• The root element is result with attributes cardinality, page and rpp (configurable results set size)
• Information about each resource that matches the query is expressed in an “lo” element with the attributes: title, description, location, oicsdata (the location of the metadata view page on the OICS repository).