CUD REST query examples

The REST interface user guide has some further examples, but some simple queries are provided below.

Prerequisites are that you have:

  • a CUD service principal
  • created a keytab
  • curl installed on your server. 

Example query

This example query searches for everyone that currently has an affiliation to your unit. 

If you run the query in the CUD UI (User Interface), below the results you will see some information text: Query Used.  This is always a very useful starting point when constructing any query that you might intend to use to query CUD via the REST interface, such as to query used:cud\:cas\:current_affiliation:lady (the backslashes are required for the REST query).

 

On your server, at the command line:

KRB5CCNAME=cudprincipalcache; kinit cud/<server>.<unit>.ox.ac.uk@OX.AC.UK -k -t <PathToKeytab>/<keytabFile>

Run an empty query:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q='

And the output is:

cud:cas:cudid,cud:cas:title,cud:cas:firstname,cud:cas:lastname,cud:cas:known_as,cud:cas:oxford_email,cud:cas:sso_username,cud:fk:university_card_sysis,cud:fk:opendoor_staff_number,cud:fk:oss_student_number,cud:cas:university_card_status,cud:cas:internal_tel,cud:cas:external_tel,cud:cas:scoped_affiliation

 

Now with an actual query:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:current_affiliation:lady'

And, all being well, you should get the full results set written to the terminal window. Better to redirect to a file:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:current_affiliation:lady' > results.csv

More options

Note that there are default fields included in the output (see the empty query, above) and that the default output is csv.  These can be changed,  but for now this page is just looking at some examples to get you started.

The AND and OR operators are available:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:lastname:Bloggs AND cud\:cas\:firstname:Joe'  >  results.csv

Combine with brackets to limit your results further:

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:cas\:lastname:Bloggs AND (cud\:cas\:firstname:Joe OR cud\:cas\:firstname:Kate)' > results.csv

 

If you have access to the University Card end-date attribute, you can query for date ranges, but you will need to escape the square bracket range limiters.

curl --negotiate -u : 'https://ws.cud.ox.ac.uk/cudws/rest/search/person?q=cud\:uas\:universitycard_comp_date:\[NOW TO *\]'  >  results.csv

That query returns everyone with a current university card so you may not want to run that query! Not without some extra parameters, anyway, to cut down the number of results. 

CUD UI login link


Core User Directory

Get support


If you cannot find the solution you need here then we have other ways to get IT support

Get IT support