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.
