Home ›

Component Registry REST interface

Web Services for the CLARIN Component Registry
 
The GUI of the CLARIN metadata editor and search services needs access to component and profile registered in the Component Registry. This REST specification should provide such access.
           
The Component Registry
 
The registry contains all CLARIN metadata components and metadata profiles used to describe all metadata. It is expected to contain around 1k components and around 1k profiles. Reuse of components and profiles is stimulated as much as possible.
Identification
 
Components and Profiles have an Id which is of type URI (this should be seen as a relaxed URI also allowing “almost” URIs like “hdl:1569/88128812”.
 
Web Services
-          list all components
-          list all profiles
-          get/post component
-          get/post profile
-          get ConceptLink from component element
-          getAncestors of Components (In which profiles is this component used, in which component is this profile used).
-          Search.
 
 
 
List all componens:
Pattern
http://cmdregistry/rest/registry/components
Examples
List all registered components
http://cmdregistry/rest/registry/components
 
Methods
GET
Get the component descriptions in the specified format
POST
Create a component in the collection of components. Returning a response containing the description of the component or the possible reasons for failing registration.
HEAD, PUT,
DELETE
Not allowed
Response
XML
Default.
JSON
Can return JSON when request-header has Accept field set to application/json.
In a curl command that would look like:
 curl -i -H "Accept:application/json" -X GET http://localhost:8080/ComponentRegistry/rest/registry/components
 
 
Return Values GET.
 
The returned values are:
ComponentDescriptions with the elements: id, name, description, registration date, creatorName, xlink:href to actual component and a groupName.
Return value examples in case of two registered components:
 
When xml is returned
<componentDescriptions>
 <componentDescription>
<id>c_1259853703335</id>
<description>Test file</description>
<name>component-access.xml</name>
<registrationDate>12/03/2009 16:21:43 CET</registrationDate>
<creatorName>J,Smith</creatorName>
<xlink:href>rest/registry/component/c_1259853703335</xlink:href>
<groupName>imdi</groupName>
</componentDescription>
<componentDescription>
<id>c_1259853703336</id>
<description>Test file 2</description>
<name>component-actor.xml</name>
<registrationDate>12/03/2009 16:21:43 CET</registrationDate>
<creatorName>J,Smith</creatorName>
<xlink:href> http://localhost:8080/ComponentRegistry/rest/registry/component/c_1259853703336</xlink:href>
<groupName>imdi</groupName>
 </componentDescription>
</componentDescriptions>
 
When json is returned
{
"componentDescription":[
{
"id":"c_1259853703335",
"description":"Test file",
"name":" component-access.xml ",
"registrationDate":"12/03/2009 16:21:43 CET ",
"creatorName":"J,Smith”,
"xlink:href":" http://localhost:8080/ComponentRegistry/rest/registry/component/c_1259853703335"},
"groupName":"imdi"
{
"id":"c_1259853703336",
"description":"Test file",
"name":" component-actor.xml ",
"registrationDate":"12/03/2009 16:21:43 CET ",
"creatorName":"J,Smith”,
"xlink:href":" http://localhost:8080/ComponentRegistry/rest/registry/component/c_1259853703336"},
"groupName":"imdi"
}
 
Note the “id”/”xlink:href” which is generated by the application and needs to be used to do a successful POST of the component data.
 
 
POST method.
A post method can be used to add Components to the registry. A post request is a Multipart Form Data consisting of the fields: “name”, “description”, “creatorName”, “group” and stream “data” part which is the uploaded component file which will be registered.
The request will be validated and the result will be wrapped in a RegisterResponse.
 
A successful POST contains the description created:
 <registerResponse registered="true" isProfile="false">
    <errors/>
    <description xsi:type="componentDescription" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <id>c_1259853703337</id>
        <description>myD</description>
        <name>Name</name>
        <registrationDate>myDate</registrationDate>
        <creatorName>myC</creatorName>
        <xlink:href> http://localhost:8080/ComponentRegistry/rest/registry/component/c_1259853703337</xlink:href>
        <groupName>imdi</groupName>
    </description>
</registerResponse>
 
An unsuccessful POST contains the errors explaining why it is not accepted:
<registerResponse registered="false" isProfile="false">
    <errors>
        <error>Error 1</error>
        <error>Error 2</error>
    </errors>
</registerResponse>
 
 
 
List all profiles:
Pattern
http://cmdregistry/rest/registry/profiles
Examples
List all registered profiles
http://cmdregistry/rest/registry/profiles
 
Methods
GET
Get the profiles in the specified format
POST
Create a profile in the collection of profiles. Returning a response containing the description of the profiles or the possible reasons for failing registration.
HEAD, PUT,
DELETE
Not allowed
Response
XML
Default.
JSON
Can return JSON when request-header has Accept field set to application/json.
 
 
Return Values GET.
 
ProfileDescriptions with the elements: id, name, description, registration date, creatorName, xlink:href to actual profile.
 
Return value examples are similar as previously described only an xml example is shown:
</profileDescriptions>
 <profileDescription>
<id>p_1257850388373</id>
<description>Test</description>
<name>TestProfile</name>
<registrationDate>Tue Nov 10 11:53:08 CET 2009</registrationDate>
<creatorName>J. Smith</creatorName>
<xlink:href> http://cmdregistry/rest/registry/profile/p_1257850388373</xlink:href>
 </profileDescription>
</profileDescriptions>
 
POST method.
Similar to post of components.
 
 
Get component:
Pattern
http://cmdregistry/rest/registry/components/<component-id>
or
http://cmdregistry/rest/registry/components/<component-id>/xml
http://cmdregistry/rest/registry/components/<component-id>/xsd
Examples
Get registered component
http://cmdregistry/rest/registry/components/clarin.eu:cr1:p0001
 
Methods
GET
Get the component in its xml format
HEAD,
PUT,
POST,
DELETE
Not allowed
Response
XML
Default.
JSON
Can return JSON when request-header has Accept field set to application/json. (Not supported with /xml and /xsd types.)
 
 
Return Values GET.
 
The returned value is:
The xml representation of the specified component. Specification of the components structure can be found in [http://trac.clarin.eu/browser/metadata/trunk/toolkit/general-component-schema.xsd].
 
Return values when specifying /xml or /xsd.
A pretty printed xml representation of the component (usefull for presenting the xml to a user)or the xsd schema of the component.
 
 
Get profile:
Pattern
http://cmdregistry/rest/registry/profiles/<profile-id>
or
http://cmdregistry/rest/registry/profiles/<component-id>/xml
http://cmdregistry/rest/registry/profiles/<component-id>/xsd
Examples
Get registered profile
http://cmdregistry/rest/registry/profiles/clarin.eu:cr1:p0001
 
Methods
GET
Get the profile in its xml format.
HEAD,
PUT,
POST,
DELETE
Not allowed
Response
XML
Default.
JSON
Can return JSON when request-header has Accept field set to application/json. (Not supported with /xml and /xsd types.)
 
Return Values GET.
See get Component.
 
The following services are not implemented yet and are still very likely to change.
 
Get ConceptLink from component element
Pattern
http://cmdregistry/rest/registry/components/<component-id>/concepts/
http://cmdregistry/rest/registry/components/<component-id>/concepts/xpath?{-join|&|query}
Examples
Get Conceptlink used in componentId ”clarin.eu:cr1:p0001” in element “Actor.Age”
http://cmdregistry/rest/registry/components/clarin.eu:cr1:p0001/concepts/xpath?query=Actor.Age
Get all concepts used in a component.
http://cmdregistry/rest/registry/components/clarin.eu:cr1:p0001/concepts/
 
 
variable        
cardinality
value
Description
variables
query
1
 
Obligatory Component ID, when using /xpath
 
 
 
 
 
Methods
GET
Get tuples of components elements as (xpath) and links to conceptElements used
HEAD, PUT,
POST,
DELETE
Not allowed
 
 
Return Values.
 
The returned value is:
The xml representation of a tuple describing the xpath of the element and a link of the conceptlink used.
 
<conceptlink cid=” clarin.eu:cr1:p0001” xpath=”Actor.Age” conceptLink= “http://www.isocat.org/datcat/DC-2550”/>
 
 
Get Ancestors of Component
Pattern
http://cmdregistry/rest/registry/components/<component-id>/ancestors?[-join|&|lmode]
 
Examples
Get Ancestor of Component. In which components/profiles is this component used?
http://cmdregistry/rest/registry/components/clarin.eu:cr1:c0001/ancestors
 
 
variable 
cardinality
value
Description
variables
lmode
?
[list|xml|json]
xml=default
Return value type
Methods
GET
Get description of Ancestor with type (Component/Profile)
HEAD, PUT,
POST,
DELETE
Not allowed
 
 
Return Values.
 
The returned value is:
The xml representation of the specified CID the Ancestor type and the ancestor description.
 
<searchResult>
<components>
<component id=” clarin.eu:cr1:c0001” name=”ComponentName” registrationDate=”DD-MM-YYYY” creatorName=”John Smit” xlink:href=” http://cmdregistry/rest/registry/component/clarin.eu:cr1:c0001”/>
</components>
<profiles>
<profile id=” clarin.eu:cr1:p0001” name=”Profile Name” registrationDate=”DD-MM-YYYY” creatorName=”John Smit” xlink:href=” http://cmdregistry/rest/registry/profile/clarin.eu:cr1:p0001”/>
</profiles>
</searchResult>
 
Search
Pattern
http://cmdregistry/rest/registry/search?[-join|&|lmode|query|type]
 
Examples
Search the registry for component and profiles with “MPI” in it?
http://cmdregistry/rest/registry/search?query=”MPI”
 
 
variable 
cardinality
value
Description
variables
lmode
?
[list|xml|json]
xml=default
Return value type
query
1
 
 
type
?
[c|p|both]
both=default
type=c for search in components only
type=p for search in profiles only
type=both for search in both.
Methods
GET
Get description of Component or Profile.
HEAD, PUT,
POST,
DELETE
Not allowed
 
 
Return Values.
 
The returned value is:
The xml representation of the component/profile description matching the query.
 
<searchResult>
<components>
<component id=” clarin.eu:cr1:c0001” name=”ComponentName” registrationDate=”DD-MM-YYYY” creatorName=”John Smit” xlink:href=” http://cmdregistry/rest/registry/component/clarin.eu:cr1:c0001”/>
</components>
<profiles>
<profile id=” clarin.eu:cr1:p0001” name=”Profile Name” registrationDate=”DD-MM-YYYY” creatorName=”John Smit” xlink:href=” http://cmdregistry/rest/registry/profile/clarin.eu:cr1:p0001”/>
</profiles>
</searchResult>
 
 
 
 
 

Accessibility
Public