The Opal JSON API

Opal features a rich, self documenting set of open JSON APIs.

Opal applications are generally simply a collection of Browser-based clients for these APIs.

Opal uses Django Rest Framework to provide it's APIs.

You may examine the API of any running Opal application by navigating to the url /api/v0.1/

Adding your own APIs

You can add your own APIs to the Opal API namespace from plugins or by registering them directly with the router.

from rest_framework.viewsets import ViewSet
from rest_framework.response import Response
from opal.core.api import router


class PingViewSet(ViewSet):
    def list(self, request): return Response('pong')

router.register('ping', PingViewSet)

APIs can make use of method decorators item_from_pk, episode_from_pk and patient_from_pk that will replace a pk passed into a method with self.model, Episode or Patient respectively.

e.g.

class SomeBespokeViewset(viewsets.Viewset):
  model = ClinicialInformation

  @item_from_pk
  def some_api_endpoint(self, request, clinical_information):
    # Some logic

Authentication

Opal uses Django Rest Framework (DRF) to provide APIs. DRF ships with multiple authentication mechanisms which are highly configurable. By default, Opal applications (e.g. created with the Opal scaffolding) will enable Sesison and Token based authentication.

More details on DRF authentication are available in their excellent documentation.

Permissioning

Opal uses the DRF permissions system for JSON APIs.

Opal ships with opal.core.api.LoginRequiredViewset which adds the permission class IsAuthenticated by default. Developers are strongly encouraged to ensure that APIs which serve patient data are restricted to logged in users.

More details on DRF permissions are available in the DRF documentation .

Session Based

Session based authentication enables users logged in via the standard Django auth mechanism to use the API. This is what most Opal applications in the browser will use.

Token Based

Token based authentication is targetted at other applications consuming the Opal API, and requires the application to pass an API token as a header. These tokens must be associated with a Django user, and can be created in the Django Admin.

An example of a client using token based authentication is found in the OpalAPI project.