CLARIN Metadata Service

This is a draft description of the REST-interface of CLARIN Metadata Service. Especially the response description is very sketchy yet.

Also the @base is an abstract one (more like a namespace). The actual URL is: http://clarin.aac.ac.at/MDService2/

Resources

resource-wide matrix parameters
parameter value description

format

string

One of:

  • xml
  • htmltable
  • htmldetail
  • htmlpage

repository

int

Default: 1

allows to dynamically select one of the available repositories for the queries.

Probably this should be rather a semantic identifier (a string-key instead of int)

cache

string

One of:

  • use (default)
  • skip
  • refresh

Default path

/?q&squery&columns&collection&startRecord&maximumRecords

This is the default application trying to make sense of any parameters that are passed. So that it is possible to bookmark/send a query as a simple URI (REST at its best ;). Sot it accepts the same parameters as the search-interface, but displays the query within the main user-interface.

Methods

GET

request template,query parameters
parameter value description

q

CQL

squery

string

just individual terms

columns

cmdIndex (repeating)

collection

URI

startRecord

positiveInteger

maximumRecords

positiveInteger

available response representations:

Collections

/collections/{format}/{collection}?maxdepth

This provides a summary of collections in the repository (it is passed on to getCollections-method of MdRepository)

Methods

GET

request template,query parameters
parameter value description

collection

URI

maxdepth

positiveInteger

available response representations:

Model

/model/{format}/{term}?q&maxdepth

This provides a summary of the xml-structure in the repository (aggregated XML-subtrees) (it is passed on to queryModel-method of MdRepository)

The starting context can be part of the url (template-style) or in the q parameter. What happens if both are defined?

Methods

GET

request template,query parameters
parameter value description

term

cmdIndex

q

cmdIndex

maxdepth

positiveInteger

available response representations:

Terms

/terms/{format}/{term}?q&maxdepth

This combines the information from MdRepository (model-interface), Component Registry and optionally Data Category Registry and RelationRegistry providing a summary of the profiles actually used in the repository together with mapping to data-categories.

Methods

GET

request template,query parameters
parameter value description

format

string

One of:

  • xml
  • flat
  • autocomplete
  • htmlselect
  • htmlpage

term

cmdIndex

One of:

  • all
  • {profile name}

q

cmdIndex

maxdepth

positiveInteger

available response representations:

Search

/recordset/{format}/?q&squery&columns&collection&startRecord&maximumRecords

This is the actual search interface allowing to retrieve MDRecords from the MDRepository. Main parameter is q expected to be a valid CQL-query. The query is translated into XPath and passed on to the searchRetrieve-method of MDRepository, which already returns a valid (SRU-protocol compliant) searchRetrieveResponse.

Methods

GET

request template,query parameters
parameter value description

q

CQL

squery

string

just individual terms

columns

cmdIndex (repeating)

collection

URI

maxDepth

positiveInteger

startRecord

positiveInteger

maximumRecords

positiveInteger

request header parameters
parameter value description

maxDepth

positiveInteger

available response representations:

Record detail

/record/{format}/{q}?cacheid

Special method for retrieving a full individual record. It is also translated into XPath (MdSelfLink) and served by the searchRetrieve-method of MDRepository.

Methods

GET

request template,query parameters
parameter value description

q

URI

PID - handle of the record

cacheid

int

Proposed parameter, to remember the recordset, the record comes in from, to be able, to retrieve it directly from MDService's cache and save the trip to MDRepository (for data, that is already locally available)

available response representations:

Workspace profile

/workspaceprofile/{type}

Delivers the configuration-structure. A server profile or an user specific (plus a special "default"-profile for the anonymous user).

The profiles are stored as xml-files on the server and handed out as JSON-files to the client.

Methods

GET

request template,query parameters
parameter value description

type

string

One of:

  • server
  • user

available response representations:

Save workspace profile

/workspaceprofilesave?data

Allows to save back the configuration-file.

Methods

POST

request template,query parameters
parameter value description

data

string

Default: public

available response representations:

Cache

/cache/{format}

Allows to view the cache-index

Methods

GET

request template,query parameters
parameter value description

format

string

One of:

  • xml
  • htmlpage

available response representations:

Cache

/cache/{format}/del?actionkey&repository&date

Allows to delete/flush (parts of) cache; parameters constraint the part of cache to be deleted; no param means: delete everything

Methods

GET

request template,query parameters
parameter value description

actionkey

string

Default: public

repository

int

Default: public

date

date

Default: public

available response representations:

Representations

text/html

application/xml (mds:Collections)

XML Schema

Source:

plain parameters
parameter value description

collection_name

QName (repeating)

  • XPath to value: //Collection
  • Link:

application/xml (mds:Terms)

XML Schema

Source:

plain parameters
parameter value description

cmdIndex

anyURI (repeating)

  • XPath to value: //mds:Terms/@path

application/xml (mds:Terms)

XML Schema

Source:

plain parameters
parameter value description

cmdIndex

anyURI (repeating)

  • XPath to value: //mds:Terms/@path

application/xml (mds:searchRetrieveResponse)

XML Schema

Source:

plain parameters
parameter value description

records

anyURI

  • XPath to value: //records

application/xml (mds:searchRetrieveResponse)

XML Schema

Source:

plain parameters
parameter value description

records

anyURI

  • XPath to value: //records

application/json (mds:WorkspaceProfile)

XML Schema

Source:

application/json (mds:WorkspaceProfile)

XML Schema

Source:

text/html

text/html