Last modified 4 years ago Last modified on 06/04/13 04:02:58

APIs: Application Programming interfaces and file formats used in COMETE

The COMETE project creates several new APIs, and uses many other as either a client or a server.

It also defines a few new file formats.

This page describes those APIs and file formats that are directly involved in the communication between COMETE modules. The COMETE project actually uses many other standards and file formats which are described elsewhere.

API design

As often as possible, the COMETE project will try to use generic REST protocols, and apply RESTfull design to new ones. For example, as much as possible, the QueryEngine API will be an extension of OpenSearch.

Aside from the mindshare RESTfull designs now enjoy, and the fact it fits our problem domain almost perfectly, REST (REpresentational State Tranfer) is a stateless protocol style modeling domain objects as resources and using http to transform their state. Our problem domain is resources shared on the web and the transformations on them.

Having RESTfull APIs available is especially important because not having them would force several modules to have boilerplate code just to retrieve and transform resource representations to serve them over http (example include RSS feeds, vocabulary entries, thumbnaild, etc.), instead of merely linking to them.

COMETE-specific APIs

These are the new APIs and file formats that the COMETE project develops. Some, like the Application profile file format, are meant to become standards.

Metadata

REST resource representing the management of metadata formats.

Transport
REST resources
Resource Operations Description
/harvestedRecords POST digest a harvested metadata record
/harvestedRecords/{oaiID} PUT,DELETE a harvested metadata record
/learningObjects POST create a learning object
/learningObjects/{id}/html GET get the html view of a learning object
/learningObjects/{id}/rdf GET get the rdf doc of a learning object
/learningObjects/count GET the count of learning objects
/learningObjects/resetAll GET re-parse all metadata records
/learningObjects/{id}/{format} GET,PUT the associated metadata record
/metadataRecords POST digest an uploaded metadata record
/metadataRecords/{id}/html GET get the html view of a metadata record
/metadataRecords/{id}/xml GET get the xml view of a metadata record
/metadataRecords/{id}/rdf GET get the rdf doc of a metadata record
/metadataRecords/applicationProfiles GET get the list of valid application profiles
/metadataRecords/applicationProfilesByColumns GET get the list of valid application profiles shown by columns
/metadataRecords/{id}/validationReport/{applProf}/xml GET get the validation report of the metadata record against a specific application profile
/repositories PUT add or update a repository record
/repositories/{id}/html GET get the html view of a repository
/repositories/{id}/rdf GET get the rdf doc of a repository
/settings/validatedApplicationProfiles GET,PUT the list of application profiles against which metadata records are validated during digestion phase.

http://dev.cometeproject.org/wiki/Architecture/APIs/Metadata#settingsvalidatedApplicationProfiles

Identity

REST resource representing an identity (a person or organisation)

Need for a new API
No such API exist
Transport
REST resources
Resource Operations Description
/identities POST Create or update an identity.
/identities/{id}/photo GET get the stream of the identity photo.
/identities/isEquivalentIdentity GET Indicate whether 2 identities are equivalent or not.
/identities/betterIdentity GET Compare 2 identities.
/identities/mergeIdentities POST Merge 2 identities.
/persons/{id}/html GET get the html view of a person.
/persons/{id}/rdf GET get the rdf doc of a person.
/persons/{id} DELETE delete a person.
/organizations/{id}/html GET get the html view of an organization.
/organizations/{id}/rdf GET get the rdf doc of an organization.
/organizations/{id} DELETE delete an organization.

Vocabulary

REST resources to represent vocabularies, and their terms.

Transport
REST resources
Resource Operations Description
/vocContexts/{id}/html GET get the html view of a voc context.
/vocContexts/{id}/rdf GET get the rdf doc of a voc context.
/vocContexts/convertVdexToSkos GET produces a SKOS doc from a VDEX one.
/voc/{source}/{cat}/rdf GET get the rdf doc of a vocabulary scheme.
/voc/{source}/{cat}/{concept} GET get the uri of a vocabulary concept that map path params.
/voc/{source}/{concept} GET get the uri of a vocabulary concept that map path params.
/voc/{source}/{cat}/{concept}/rdf GET get the rdf doc of a vocabulary concept.
/voc/all GET get all vocabularies.
/voc/{source}/{cat}/topConcepts GET get the skos top concepts of a vocabulary.
/voc/{source}/{cat}/{concept}/children GET get the skos narrower concepts of a concept.
/voc/graphName GET get the store graphname of a concept or concept scheme.

LinkedData

Dereferencing of the URI to their associated RDF data (either in raw RDF or more human-friendly HTML). This is a READ-ONLY API.

Transport
REST resources
Resource Operations Description
/learningobject/{id} GET Persistent URI of a learning object.
/learningobject/{id}.rdf GET URI of the raw RDF data of a learning object.
/learningobject/{id}/incomingLinks.rdf GET Incoming links pointing to the learning object.
/learningobject/{id}.html GET URI of the HTML view of the RDF data of a learning object.
/metadatarecord/{id} GET Persistent URI of a metadata record.
/metadatarecord/{id}.rdf GET URI of the raw RDF data of a metadata record.
/metadatarecord/{id}/incomingLinks.rdf GET Incoming links pointing to the metadata record.
/metadatarecord/{id}.html GET URI of the HTML view of the RDF data of a metadata record.
/person/{id} GET Persistent URI of a person.
/person/{id}.rdf GET URI of the raw RDF data of a person.
/person/{id}/incomingLinks.rdf GET Incoming links pointing to the person.
/person/{id}.html GET URI of the HTML view of the RDF data of a person.
/organization/{id} GET Persistent URI of a organization.
/organization/{id}.rdf GET URI of the raw RDF data of a organization.
/organization/{id}/incomingLinks.rdf GET Incoming links pointing to the organization.
/organization/{id}.html GET URI of the HTML view of the RDF data of a organization.
/repository/{id} GET Persistent URI of a repository.
/repository/{id}.rdf GET URI of the raw RDF data of a repository.
/repository/{id}/incomingLinks.rdf GET Incoming links pointing to the repository.
/repository/{id}.html GET URI of the HTML view of the RDF data of a repository.
/voccontext/{id} GET Persistent URI of a vocabulary context.
/voccontext/{id}.rdf GET URI of the raw RDF data of a vocabulary context.
/voccontext/{id}.html GET URI of the HTML view of the RDF data of a vocabulary context.
/voc/{source}/{cat} GET Persistent URI of a vocabulary scheme.
/voc/{source}/{cat}.rdf GET URI of the raw RDF data of a vocabulary scheme.
/voc/{source}/{cat}/{concept} GET Persistent URI of a vocabulary concept.
/voc/{source}/{cat}/{concept}.rdf GET URI of the raw RDF data of a vocabulary concept.
/voc/{source}/{cat}/{concept}/incomingLinks.rdf GET Incoming links pointing to the vocabulary concept.
/voc/{source}/{cat}/{concept}.html GET URI of the HTML view of the RDF data of a vocabulary concept.

QueryEngine

REST resource representing the query engine to search for resources.

The QueryEngine API is used to perform searches on the resources and get the result in various formats (like OpenSearch, !Atom, !JSON, etc.)

Transport
REST resources
Resource Operations Description
/searchJson GET List of JSON-formatted resources matching simple keywords query.
/searchAtom GET List of Atom-formatted resources matching simple keywords query.
/advancedSearchJson GET List of JSON-formatted resources matching multiple criterias query.

Harvester

REST resource representing Harvester definitions and status.

Need for a new API
We need a programmatic way to get data from a Harvester.
Detailed documentation
Architecture/APIs/Harvester
Transport
Read-only REST resources. For now, the modification services are supported by the web interface.
Resource Operations Description
/ GET List all harvester definitions
/{identifier} GET Fetch the configuration of a harvester definition
/{identifier}/reports GET List all harvesting reports associated to a harvester definition
/{identifier}/reports/{date} GET Fetch a specific report associated to a harvester definition
/{identifier}/reports/last GET Fetch last harvesting report associated to a harvester definition
/{identifier}/reports/{date}/{metadataPrefix} GET Fetch the collect report associated to a harvester definition for a specific metadata prefix

Registry

REST resource representing Metadata on Repositories. This API creates a bridge between COMETE and existing deployed registries.

Need for a new API
We need a programmatic way to manipulate the data in the registry.
Detailed documentation
Architecture/APIs/Registry
Transport
REST resources
Resource Operations Description
/ GET List all registries
/{registry} PUT, DELETE A registry
/{registry}/collections GET The collections in a registry.
/{registry}/protocols GET The protocols in a registry.
/{registry}/targets GET The targets in a registry.
/{registry}/collections/{catalog},{entry} GET,PUT,DELETE A collection in a registry
/{registry}/protocols/{catalog},{entry} GET,PUT,DELETE A protocol in a registry
/{registry}/targets/{catalog},{entry} GET,PUT,DELETE A target in a registry
/{registry}/items/search GET Query a registry for a specific item

AriadneRegistry

The current version of registry allows REST-like requests of the following form:

Despite the format=lom parameter, the returned format is the one described in the LODE Specifications document. Only search is supported, it is not possible to write new metadata or update existing ones with the REST-like API. Do we want to support that?

Additional currently supported query methods:

  • OAI-PMH
  • SQI

IdentityEditor

Very simple API to call the appropriate identity editors (VCard, FOAF, etc.) either stand-alone, or as part of a resource metadata editor.

Need for a new API
Normally the workflow should be flexible enough to perform this task, if it wasn't for the need to call it embedded in the metadata editor.
Transport
To be determined
Data exchange
In Stored Out
Identity in editor specific format, List of editable fields Edited Metadata in the same format

VocabularyEditor

Very simple API to call the appropriate vocabulary editors (VDEX, SKOS, OWL, etc.) on the entire vocabulary or a single term.

Need for a new API
Only if we actually implement a web editor. The Vocabulary API provides all we need if we only edit vocabularies offline as a whole.
Transport
To be determined
Data exchange
In Stored Out
Vocabulary in editor specific format, List of editable fields Edited Metadata in the same format
Vocabulary term in editor specific format, List of editable fields Edited Metadata in the same format

MetadataEditor

REST resource representing the metadata editors.

Need for a new API
We need to send application profile information to the Editor, and we want a non-SOAP protocol to make the editor more independent of other ORI-OAI modules.
Detailed documentation
Architecture/APIs/MetadataEditor
Transport
Currently SOAP, to be moved to REST when it is expanded for Application Profile support.
Data exchange
In Stored Out
Metadata in editor specific format, Application Profile Edited Metadata in the same format

AppProfile

Resource representing different application profiles.

Need for a new API
We need a representation for the profiles that allows both editing the profile, validating metadata against it, and configuring the metadata. editor.
Detailed documentation
Architecture/APIs/AppProfile
Transport
A very simple REST protocol to store and retrieve application profiles File formats: An XML format to describe application profiles and an XML Schema to describe that format.
Data exchange
In Stored Out
Application Profile Metadata Application Profile Metadata Application Profile identifier
Application Profile identifier Application Profile Metadata

COMETE-extended APIs

Those APIs are standards that are significantly extended or modified by COMETE.

OpenSearch

The OpenSearch protocol, with COMETE specific extensions to implement the functionnality of the query engine.

AVS-REST

The Ariadne Validation Service REST API, with COMETE enhancements to allow:

Externally defined APIs

Those APIs are standards that are directly reused for communication between COMETE modules.

CMIS

Content Management Interoperability Service. See CMIS

OAI-PMH

Open Archives Initiative Protocol for Metadata Harvesting. See OAI-PMH

SQI

Simple Query interface. See SQI

SRU

Search/Retrieval via URL. See SRU

SPARQL

SPARQL Protocol and RDF Query Language. The analog of SQL for relational databases. See SPARQL

In the case of Fedora, the Trippi library is used as an abstraction layer, like JDBC would be for a relational database.

TQL

TQL Query Language. Used as SPARQL update for Mulgara. See TQL

Fedora APIs

The following Fedora-specific APIs are used by COMETE :

Fedora REST API

The Fedora REST API exposes a subset of the Fedora Access and Management APIs as a RESTful Web Service

RISearch

The Resource Index Search Service (RISearch) is a web service that exposes the contents of a repository's Resource Index guide for outside use. It allows searching the relationships for Tuples and Triples using, among other choices, SPARQL

Documentation: https://wiki.duraspace.org/display/FCR30/Resource+Index+Search

SDef

Not an API per see, a Service Definition ("SDef") is a special kind of object that defines a set of operations on objects in a repository.

Documentation: https://wiki.duraspace.org/display/FCR30/Creating+a+Service+Definition

SDep

Not an API per see, a Service Deployment ("SDep") is a special kind of object that describes how the methods of a particular Service Definition are to be deployed for a particular Content Model.

Documentation: https://wiki.duraspace.org/display/FCR30/Creating+a+Service+Deployment

0.9.8 © 2008-2011 Agilo Software all rights reserved (this page was served in: 0.78754 sec.)