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 descibed using URI templates. When an URL can return various resource representations those 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. an 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 thematic profile
URL
Pattern	http://www.isocat.org/rest/profile/{id}?{-join|&|scope,hoist,dcif-mode}
Examples	http://www.isocat.org/rest/profile/5 http://www.isocat.org/rest/profile/5?hoist=false http://www.isocat.org/rest/profile/5?hoist=false&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 hoist ? true|false include or exclude Data Categories from profiles nested in the specified profile true (default) include Data Categories from profiles nested in the specified profile false don't include Data Categories from profiles nested in the specified profile 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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type 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	http://www.isocat.org/rest/dcs/{id}?{-join|&|hoist,dcif-mode,profile,workingLanguage,objectLanguage}
Examples	http://www.isocat.org/rest/dcs/4 http://www.isocat.org/rest/dcs/4?hoist=false http://www.isocat.org/rest/dcs/4?hoist=false&dcif-mode=list
Input
Variables	variable cardinality value description notes id 1 [0-9]+ the Data Category Selection id hoist ? true|false include or exclude Data Categories from selections nested in the specified Data Category Selection true (default) include Data Categories from selections nested in the specified Data Category Selection false don't include Data Categories from selections nested in the specified Data Category Selection 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 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 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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource	a Data Category
URL
Pattern	http://www.isocat.org/rest/dc/{id}?{-join|&|profile,workingLanguage,objectLanguage}
Examples	http://www.isocat.org/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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type text/html HyperText Markup Language

Resource	a user's private Data Categories
URL
Pattern	http://www.isocat.org/rest/user/{username}/private?{-join|&|dcif-mode}
Example	http://www.isocat.org/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 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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource	a search result
URL
Pattern	http://www.isocat.org/rest/user/{username=guest}/search?{-join|&|keywords,fields,language,match,limit,profile,scope,dcif-mode}
Examples	http://www.isocat.org/rest/user/guest/search?keywords=chinese http://www.isocat.org/rest/user/guest/search?keywords=chinese han&fields=identifier name http://www.isocat.org/rest/user/guest/search?keywords=chinese&keywords=han&fields=identifier name http://www.isocat.org/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 in the Data Category Specification to investigate the list of fields can also be distributed over various fields 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 how to match the keywords like (default) do a case insensitive fulltext search exact do a case sensitive phrase search this match mode is only applied to the identifier, name or element fields, all other fields always use the fulltext 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 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 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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type application/rdf+xml Resource Description Framework for this representation the value of the dcif-mode variable is ignored

Resource	an adhoc selection
URL
Pattern	http://www.isocat.org/rest/user/{username=guest}/basket?{-join|&|dc}
Examples	http://www.isocat.org/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
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/dcif+xml (default) Relax NG Data Category Interchange Format this is not (yet) a IANA registered +xml media type application/rdf+xml Resource Description Framework for this representation the value of the mode variable is ignored