This page is obsolete. It is kept here for archival purposes, but for an up-to-date version please see the DigiPal Framework wiki on GitHub at https://github.com/kcl-ddh/digipal/wiki/.


The Web API exposes the DigiPal Django Models as a Restful web API. It handles CRUD requests from HTTP and returns JSON responses. For further information see the full developer's documentation on the GitHub repository.

Request

Here is the general form for the requests

(HTTP-METHOD) http://www.digipal.eu/digipal/api/:content_type/[:selector/]?[_:filter=:value1][&@select=[*]:fieldset1,[*]:fieldset2,...][&:field=:value2][&@limit=:limit][&@format=:format] 
  • : is used to denote a variable. All variables are described in the section below.
  • optional parameters are surrounded by []

Request parameters

HTTP-METHOD

  • GET : to retrieve records
  • PUT : to update records

:content_type

The name of DigiPal model in lower case (e.g. annotation, image, itempart, graph)

:selector

A comma separated list of record ids. If not supplied no filter is applied (all records are returned). This is functionally equivalent to 

?_id__in=[:selector]

e.g. 

GET /digipal/api/annotation/1000,1001/

=> retrieves annotation records with id = 1000 or 1001 

:filter

Any Django valid QuerySet filter that can be applied to the model specified in :content_type. Note that filters must start with an underscore. You can use more than one filter. For filter reference see the Django documentation.

String values shouldn't be surrounded by quotes and booleans can be expressed with 0 (False) or 1 (True).

e.g. 

GET /digipal/api/annotation/?_graph__id__gt=2000&_rotation=0

=> retrieves annotation where annotation.graph.id > 2000 AND annotation.rotation = 0

e.g. 

GET /digipal/api/itempart/?_pagination=1&_display_label__icontains=badminton

=> retrieves itemparts where itempart.pagination = True and itempart.display_label contains 'badminton'

:fieldset

A field name from the requested content_type or a custom-defined fieldset. If @select is not provided all fields are returned. Note that the field 'id' is always returned. 'str' is a special field that corresponds to the string representation of the record. For related records only the id is returned. However, you can use * to expand the information about related records or explicitly specify the fields of the related records (see examples below).

e.g. 

GET /digipal/api/annotation/1000/

=> returns all the fields of annotation 1000

e.g. 

GET /digipal/api/annotation/?@select=rotation,modified

=> returns only annotation.id, annotation.rotation and annotation.modified e.g. 

GET /digipal/api/annotation/?@select=myset

=> returns a custom-defined set of fields named 'myset'. This fieldset is defined in custom.py:APIAnnotation()

e.g. 

GET /digipal/api/annotation/1000/?@select=graph

=> returns only 'id' and 'graph__id' and 'graph' (string repr of the associated graph record)

e.g. 

GET /digipal/api/annotation/1000/?@select=*graph

=> returns only 'id' and 'graph', with graph being a dictionary with id

e.g.

GET /digipal/api/itempart/?@select=str,*hands,label,scribe

=> returns the string representation of the item part, along with the label and scribe of all associated hand records.

:field

A field to be changed in the retrieved records. You can provide multiple fields. 

e.g. 

PUT /digipal/api/annotation/1000/?rotation=20&image_id=500

=> change the rotation and the image of the annotation record with id = 1000

:limit

Maximum number of records the operation works on. If unspecified the limit is DEFAULT_RESULT_SIZE. This is to avoid accidental requests retrieving too many records by mistake.

:format

The desired output format for the response. Supported formats are: json, jsonp and xml. If not provided the output format is json. If @callback is specified, the output format is always jsonp (@format is ignored). 

e.g. 

GET /digipal/api/annotation/?@format=xml

=> returns annotation records in a XML format

Response

 { 'success': boolean, 'errors': [], 'count': the size of the result set BEFORE applying @limit 'results': [ {'id': , 'field1': 'field2': ... }, ... ] } 

Geoffroy Noel