Parameters are included in the query string. These should be URL-encoded (there are plenty of free URL-encoding utilities available both on and off the web).
Allowed parameters are as follows:
This is the parameter describing the Solr query, and is the only mandatory parameter.
Legal values are empty (no data will be returned), or a legal Solr query.
An example of the Solr query cud\:cas\:sso_username:unit1234, when encoded:
The Solr query cud\:cas\:sso_username:unit1234 AND cud\:cas\:current_affiliation:oucs, when encoded:
The fields parameter allows the requestor to reduce the set of values returned for each record to only those attribute fields that are specified.
Legal values are a comma-separated list of attribute names.
An example of the fields parameter used to specify the Oxford email and CUD ID (cud:cas:oxford_email,cud:cas:cudid):
The format parameter in CUD queries is optional, and specifies the format in which the requested data will be returned. It may be omitted, in which case the default 'csv' format will be used.
Legal values are 'csv' (the default), 'xml', 'json', or 'text'. If 'text' is chosen you can optionally set the 'delimiter' and 'qualifier' parameters to further customise the output.
An example of the format parameter being used to specify data returned as XML:
The delimiter parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used as the field delimiter. If the text format is set, and this parameter is omitted, a comma will be used as the delimiter.
An example of the text format using a specific delimiter (|):
The qualifier parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used. The purpose of this parameter is generally to escape the field. If the text format is set, and this parameter is omitted, no additional qualifier will be used.
An example of the text format using a specific delimiter (|) and qualifier (@):
The history parameter in CUD queries is optional, and indicates whether you wish the response to contain historical values for attributes and affiliations. You should only request this if it is required, and the default is not to include history. Include history if you wish are requesting data in XML or JSON format and wish it to be richly structured (see the CUD UI User Guide for further details).
Legal values are 'y', 'n' or omitted entirely.
An example of the history parameter used to request historical data in an XML format:
Normally the Character Set encoding of the response returned by the query defaults to the modern standard set referred to as UTF8. You should not usually need to change this. However, if your application calling the query does not support UTF8, you can specify an alternative with the encoding parameter. The supported Character Sets are those available from the Java SE 7 platform used by the CUD web-service, the Java SE documentation provides a comprehensive list. The encoding parameter specifies the canonical Character Set name from that list.
A typical case where this is needed is if the calling program supports the ASCII (US-ASCII) Character Set, which is only a subset of UTF8. An example of this usage would be:
This will request the server to modify the response output to ensure that the response characters all conform to the specified encoding. In this case for ASCII, all of the output characters which are actually UTF8 but not ASCII will be changed to the ASCII question mark character "?".
This also handles the situation where UTF8 characters which are actually made up of multiple underlying bytes, for example the character "ö" is a 2-byte UTF8 character (0xC3B6). The encoding=ASCII parameter will ensure that two bytes are replaced by a single "?".
For format=xml, the CUD web-service will also modify the XML header tag accordingly: <?xml version="1.0" encoding="UTF8"?> would be changed to <?xml version="1.0" encoding="ASCII"?>.