ISOcat logo
RESTful web service interface

ISOcat provides a RESTful web services interface. The interface consists of a set of URLs which locate the resources stored in the DCR. The URLs are described using URI templates. When a URL can return various resource representations they can be selected using server-driven content negotiation using the Accept request-header field.

The interface is also described in a WADL document.

This is a beta-level interface to ISOcat. The following features of this interface are yet too be designed/implemented/tested:

  1. the experimental WADL service description (note: the document is valid, but the WADL tools seem not to be able to handle RelaxNG schemas although they're allowed by the specification)
  2. HEAD requests
  3. some of the not allowed methods (PUT, POST) are actually part of the private ISOcat RESTful interface, but should be blocked for public access
  4. users of the API should also accept the ISOcat disclaimer, so maybe we need to hand out keys like for example Google does for its Maps API

The following resources are supported:

  1. a user's workspace
  2. a thematic profile
  3. a Data Category Selection
  4. a Data Category
  5. a user's private Data Categories
  6. a search result
  7. an adhoc selection
Resource a user's workspace
URL
Pattern https://catalog.clarin.eu/isocat/rest/user/{username=guest}/workspace
Example https://catalog.clarin.eu/isocat/rest/user/guest/workspace
Input
Variable
variable cardinality value description notes
username 1 [a-zA-Z0-9_]+ the unique name which identifies the user in the system
guest the default 'guest' username gives access to the public contents of the DCR
Methods
method(s) description notes
HEAD check if the workspace exists, i.e., basically a check if the user exists
GET get the workspace of the specified user
PUT, POST, DELETE not allowed
Notes To get access to a registered user's workspace authentication is required.
Output
Status codes
code method(s) description notes
200 OK HEAD the user's workspace was found
200 OK GET the user's workspace was found and returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no user with this user name, so also no workspace
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/xml (default) Relax NG propriety ISOcat XML representation of a user's workspace

Resource a thematic profile
URL
Pattern https://catalog.clarin.eu/isocat/rest/profile/{id}?{-join|&|scope,workingLanguage,objectLanguage,dcif-mode}
Examples https://catalog.clarin.eu/isocat/rest/profile/5
https://catalog.clarin.eu/isocat/rest/profile/5?dcif-mode=list
Input
Variables
variable cardinality value description notes
id 1 [0-9]+ the profile id
scope ? public|private|both the scope of the included Data Categories
public (default) only include public Data Categories
private only include private Data Categories
both include both public and private Data Categories
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
dcif-mode ? list|domains|all determines how much information will be included in the DCIF document
list a list of Data Categories which are member of the profile
domains (default) a list of Data Categories which are member of the profile, and include the conceptual domains of the complex Data Categories
all the full specification of the Data Categories which are member of the profile
Methods
method(s) description notes
HEAD check if a profile with the specified id exists
GET get the specified profile
PUT, POST, DELETE not allowed
Notes All profiles are publically accessible. However, individual included Data Categories may not be accessible without authentication.
Output
Status codes
code method(s) description notes
200 OK HEAD a profile with the specified id was found
200 OK GET the specified profile was found and returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no profile with this id
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource a Data Category Selection
URL
Pattern https://catalog.clarin.eu/isocat/rest/dcs/{id}?{-join|&|profile,workingLanguage,objectLanguage,dcif-mode}
Examples https://catalog.clarin.eu/isocat/rest/dcs/388
https://catalog.clarin.eu/isocat/rest/dcs/388?dcif-mode=list
Input
Variables
variable cardinality value description notes
id 1 [0-9]+ the Data Category Selection id
profile * .+ limit the view on the Data Categories to a specific profile (or set of profiles) this determines which profile value domains are included
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
dcif-mode ? list|domains|all determines how much information will be included in the DCIF document
list a list of Data Categories which are member of the Data Category Selection
domains (default) a list of Data Categories which are member of the Data Category Selection, and include the conceptual domains of the complex Data Categories
all the full specification of the Data Categories which are member of the Data Category Selection
Methods
method(s) description notes
HEAD check if a Data Category Selection with the specified id exists
GET get the specified Data Category Selection
PUT, POST, DELETE not allowed
Notes For private Data Category Selections authentication is required.
Output
Status codes
code method(s) description notes
200 OK HEAD a Data Category Selection with the specified id was found
200 OK GET the specified Data Category Selection was found and returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no Data Category Selection with this id
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource a Data Category
URL
Pattern https://catalog.clarin.eu/isocat/rest/dc/{id}?{-join|&|profile,workingLanguage,objectLanguage}
Examples https://catalog.clarin.eu/isocat/rest/dc/1297?workingLanguage=en&objectLanguage=it&objectLanguage=de
Input
Variables
variable cardinality value description notes
id 1 [0-9]+ the Data Category id
profile * .+ limit the view on the Data Categories to a specific profile (or set of profiles) this determines which profile value domains are included
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
Methods
method(s) description notes
HEAD check if a Data Category with the specified id exists
GET get the specified Data Category
PUT, POST, DELETE not allowed
Notes For private Data Categories authentication is required.
For persistent references to a Data Category the URL specified as its Persistent IDentifier must be used. Currently these PIDs get redirected (using HTTP 307 redirection) to this RESTful web service, however, this interface may change in the future while the PID remains constant.
Output
Status codes
code method(s) description notes
200 OK HEAD a Data Category with the specified id was found
200 OK GET the specified Data Category was found and its specification returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no Data Category with this id
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework
text/html HyperText Markup Language

Resource a user's private Data Categories
URL
Pattern https://catalog.clarin.eu/isocat/rest/user/{username}/private?{-join|&|profile,workingLanguage,objectLanguage,dcif-mode}
Example https://catalog.clarin.eu/isocat/rest/user/somebody/private
Input
Variables
variable cardinality value description notes
username 1 [a-zA-Z0-9_]+ the unique name which identifies the user in the system
profile * .+ limit the view on the Data Categories to a specific profile (or set of profiles) this determines which profile value domains are included
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
dcif-mode ? list|domains|all determines how much information will be included in the DCIF document
list a list of Data Categories which are owned by the specified user
domains (default) a list of Data Categories which are owned by the specified user, and include the conceptual domains of the complex Data Categories
all the full specification of the Data Categories which are owned by the specified user
Methods
method(s) description notes
HEAD basically a check if the user exists
GET get the private Data Categories of the specified user
PUT, POST, DELETE not allowed
Notes Authentication is required.
Output
Status codes
code method(s) description notes
200 OK HEAD an account for the user was found
200 OK GET the private Data Categories of the specified user were found and returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no account for this user
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource a search result
URL
Pattern https://catalog.clarin.eu/isocat/rest/user/{username=guest}/search?{-join|&|keywords,fields,language,match,limit,profile,scope,type,workingLanguage,objectLanguage,dcif-mode}
Examples https://catalog.clarin.eu/isocat/rest/user/guest/search?keywords=chinese
https://catalog.clarin.eu/isocat/rest/user/guest/search?keywords=chinese&type=simple
https://catalog.clarin.eu/isocat/rest/user/guest/search?keywords=chinese han&fields=identifier name
https://catalog.clarin.eu/isocat/rest/user/guest/search?keywords=chinese&keywords=han&fields=identifier name
https://catalog.clarin.eu/isocat/rest/user/guest/search?keywords=chinese&fields=identifier name&match=exact
Input
Variables
variable cardinality value description notes
username 1 [a-zA-Z0-9_]+ the unique name which identifies the user in the system
guest the default 'guest' username gives access to the public contents of the DCR
keywords + .+ a space seperated list of keywords to match in the fields of the Data Category specifications the list of keywords can also be distributed over various keywords variables
fields * identifier|name|element|definition|explanation|example|note a space seperated list of fields to investigate in the Data Category Specification the list of fields can also be distributed over various field variables
the default is to investigate all fields
identifier match the identifier field in a Administration Record
name match the name field in a Name Section
element match the name field in a Data Element Name Section
definition match the definition field in a Definition Section
explanation match the explanation field in a Explanation Section
example match the example field in a Example Section
note match the note field in a Language Section
language ? en|da|de|es|fi|fr|hu|it|nl|no|pt|ro|ru|sv|tr|und the language of the keywords
en (default) english use the english stemmer and stop word list for fulltext searches where possible
da|de|es|fi|fr|hu|it|nl|no|pt|ro|ru|sv|tr supported search languages use the language specific stemmer and stop word list for fulltext searches where possible
und any other language this will prevent the use of language specific stemmers, stop words lists etc.
match ? like|exact|substring how to match the keywords
like (default) do a case insensitive fulltext search
exact do a case insensitive phrase search
substring do a case sensitive substring search
limit ? [0-9]+ the maximum number of results to return (default: 100)
profile * .+ the search will only return Data Categories which are a member of at least one of these profiles this also determines which profile value domains are included
type * container|simple|complex|open|constrained|closed the type of the included Data Categories
container include container Data Categories
simple include simple Data Categories
complex include any type of complex Data Categories (open, constrained, closed)
open include open Data Categories
constrained include constrained Data Categories
closed include closed Data Categories
scope ? public|private|both the scope of the included Data Categories
public (default) only include public Data Categories
private only include private Data Categories
both include both public and private Data Categories
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
dcif-mode ? list|domains|all determines how much information will be included in the DCIF document
list a list of Data Categories which matched the search
domains (default) a list of Data Categories which matched the search, and include the conceptual domains of the complex Data Categories
all the full specification of the Data Categories which matched the search
Methods
method(s) description notes
HEAD check if a Data Category Selection with the specified id exists
GET get the specified Data Category Selection
PUT, POST, DELETE not allowed
Notes Only Data Categories to which the authenticated user has access are included in the response.
Output
Status codes
code method(s) description notes
200 OK HEAD a Data Category Selection with the specified id was found
200 OK GET the specified Data Category Selection was found and returned
401 Unauthorized HEAD, GET unauthorized access
404 Not Found HEAD, GET there is no Data Category Selection with this id
405 Method Not Allowed PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource an adhoc selection
URL
Pattern https://catalog.clarin.eu/isocat/rest/user/{username=guest}/basket?{-join|&|dc,profile,workingLanguage,objectLanguage}
Examples https://catalog.clarin.eu/isocat/rest/guest/basket?dc=58&dc=59&dc=60
Input
Variables
variable cardinality value description notes
username 1 [a-zA-Z0-9_]+ the unique name which identifies the user in the system
guest the default 'guest' username gives access to the public contents of the DCR
dc + [0-9]+ a Data Category id
profile * .+ limit the view on the Data Categories to a specific profile (or set of profiles) this determines which profile value domains are included
workingLanguage * .+ limit the view on the Data Categories to a specific working language (or set of working languages) this determines which language sections are included
objectLanguage * .+ limit the view on the Data Categories to a specific object language (or set of object languages) this determines which linguistic sections are included
Methods
method(s) description notes
GET get the specified selection
HEAD, PUT, POST, DELETE not allowed
Notes Only Data Categories to which the authenticated user has access are included in the response.
Output
Status codes
code method(s) description notes
200 OK GET the specified selection was returned
405 Method Not Allowed HEAD, PUT, POST, DELETE method not allowed
Resource representations
MIME type schema description notes
application/x-dcif+xml (default) Relax NG Data Category Interchange Format
application/rdf+xml Resource Description Framework for this representation the value of the mode variable is ignored