4. API Development

Each resource available on the REST API is implemented in terms of a couple objects. The main one is a ViewSet, which may optionally use a Serializer and a FilterSet.

This is a guide for adding new resources.

4.1. Checklist

  1. Identify where to implement it: it can be part of existing application or you can create a new application. If you want a new application, use

    $ mkdir pdc/apps/your_app
$ python manage.py startapp your_app pdc/apps/your_app

  2. Create your models. Make sure to implement export method for each model that will be editable through the API.

  3. Generate migrations

    $ python manage.py makemigrations your_app

  4. Make sure the ViewSet inherits from StrictQueryParamMixin to properly handle unknown query parameters.

  5. If the resource objects can be created, updated or deleted, use ChangeSet* mixins (or PDCModelViewSet as single parent).

  6. The docstring of the methods will be visible in browsable documentation. Use Markdown for formatting. See below for other helpers you can use to simplify documentation.

  7. Serializer should inherit from StrictSerializerMixin or implement the same logic itself (report error when unknown field is specified).

  8. Write test cases for both success and error paths.

4.2. Writing documentation

The browsable documentation is exported from docstrings of view set methods. It uses Markdown as a markup language. There are a couple helpers that make some things easier.

First of all, string %(HOST_NAME)s, %(API_ROOT)s expand to host name of the current server and path to the API root, respectively.

To include a link to another resource, rather than using the macros above, there is a better way:

  • $URL:resourcename:param1$ will expand to URL to that resource. Examples:
    • $URL:release-list$ → http://pdc.example.com/rest_api/v1/releases/
    • $URL:product-detail:dp$ → http://pdc.example.com/rest_api/v1/products/dp/
  • $LINK:resourcename:param1:param2$ will expand to clickable link to that resource. The link label will be the URL of the resource (without the host name).

To describe available query filters, use %(FILTERS)s macro. This expands to an unordered list with filter names and types of the value. The serializer can be described with %(SERIALIZER)s, which expands to a code block with JSON describing the data. For create/update actions you may need to use %(WRITABLE_SERIALIZER)s which excludes all read-only fields.