The lookupapi Application¶

The lookupapi application provides a REST-y API which proxies the University of Cambridge Lookup API. Currently only the anonymous API is proxied but access to the API is protected by requiring an OAuth2 token with the appropriate scopes (lookupapi.views.REQUIRED_SCOPES). The OAuth2 token is verified by means of a third-party OAuth2 token introspection endpoint.

Installation¶

Add the lookupapi application to your INSTALLED_APPS configuration as usual. Make sure to configure the various LOOKUP_API_OAUTH2_... settings.

Default settings¶

Default settings values for the lookupapi application.

lookupapi.defaultsettings.LOOKUP_API_ENDPOINT_HOST = 'lookup-test.csx.cam.ac.uk'¶: Hostname of proxied Lookup API endpoint. This is usually one of “lookup-test.csx.cam.ac.uk” or “www.lookup.cam.ac.uk” depending on whether you want to interact with the test or production Lookup instances.

lookupapi.defaultsettings.LOOKUP_API_ENDPOINT_PORT = 443¶: Port to connect to proxied Lookup API on. Defaults to the HTTPS service port 443.

lookupapi.defaultsettings.LOOKUP_API_ENDPOINT_BASE = ''¶: Base path for proxied Lookup API. If using the deployed test or production instances this should be the empty string.

lookupapi.defaultsettings.LOOKUP_API_ENDPOINT_VERIFY = True¶: Specify whether the certificate presented by the proxied Lookup API should be checked. Unless you are extremely sure in what you are doing, set this to True.

lookupapi.defaultsettings.OAUTH2_CLIENT_ID = None¶: OAuth2 client id which the API server uses to identify itself to the OAuth2 token introspection endpoint.

lookupapi.defaultsettings.OAUTH2_CLIENT_SECRET = None¶: OAuth2 client secret which the API server uses to identify itself to the OAuth2 token introspection endpoint.

lookupapi.defaultsettings.OAUTH2_TOKEN_URL = None¶: URL of the OAuth2 token endpoint the API server uses to request an authorisation token to perform OAuth2 token introspection.

lookupapi.defaultsettings.OAUTH2_INTROSPECT_URL = None¶: URL of the OAuth2 token introspection endpoint. The API server will first identify itself to the OAuth2 token endpoint and request an access token for this endpoint.

lookupapi.defaultsettings.OAUTH2_INTROSPECT_SCOPES = None¶: List of OAuth2 scopes the API server will request for the token it will use with the token introspection endpoint.

lookupapi.defaultsettings.OAUTH2_MAX_RETRIES = 5¶: Maximum number of retries when fetching URLs from the OAuth2 endpoint or OAuth2 authenticated URLs. This applies only to failed DNS lookups, socket connections and connection timeouts, never to requests where data has made it to the server.

Views and serializers¶

Views for lookupapi.

lookupapi.views.REQUIRED_SCOPES = ['lookup:anonymous']¶: List of OAuth2 scopes requires to access the Lookup API.

class lookupapi.views.ViewPermissionsMixin¶: A mixin class which specifies the authentication and permissions for all API endpoints.

class lookupapi.views.PersonFetchAttributes(**kwargs)¶

All valid attributes for a person.

serializer_class¶: alias of lookupapi.serializers.AttributeSchemeListSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class lookupapi.views.InstitutionFetchAttributes(**kwargs)¶

All valid attributes for a institution.

serializer_class¶: alias of lookupapi.serializers.AttributeSchemeListSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class lookupapi.views.PersonList(**kwargs)¶

Search for people using a free text query string. This is the same search function that is used in the Lookup web application. By default, only a few basic details about each person are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

serializer_class¶: alias of lookupapi.serializers.PersonListResultsSerializer

count_query_keys = ['query', 'approxMatches', 'includeCancelled', 'misStatus', 'attributes']¶: Query keys which are used by both searchCount and search.

full_query_keys = ['offset', 'limit', 'fetch', 'orderBy']¶: Query keys which are used only by search.

class lookupapi.views.Person(**kwargs)¶

Retrieve information on a person by scheme and identifier within that scheme. The scheme is usually “crsid” and the identifier is usually that person’s crsid.

If the scheme is “mock” then data from the test user mug99 is returned with the corresponding identifier from the API call.

If the scheme “token” and identifier “self” is used then if the user has been authenticated it will return the lookup data of the authenticated user.

serializer_class¶: alias of lookupapi.serializers.PersonSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class lookupapi.views.Group(**kwargs)¶

Retrieve information on a group by groupid.

serializer_class¶: alias of lookupapi.serializers.GroupSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class lookupapi.views.InstitutionList(**kwargs)¶

Return a list of all institutions known to Lookup.

serializer_class¶: alias of lookupapi.serializers.InstitutionListResultsSerializer

class lookupapi.views.Institution(**kwargs)¶

Retrieve information on an institution by instid.

serializer_class¶: alias of lookupapi.serializers.InstitutionSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

class lookupapi.views.Health(**kwargs)¶

Returns a HTTP 200 response when the application is running. Can be used as a readiness probe.

serializer_class¶: alias of lookupapi.serializers.HealthSerializer

get_object()¶

Returns the object the view is displaying.

You may want to override this if you need to provide non-standard queryset lookups. Eg if objects are referenced using multiple keyword arguments in the url conf.

Django REST framework “serializers” for Lookup object.

class lookupapi.serializers.Base64Field(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)¶

Serialises binary data as base64.

to_representation(obj)¶: Transform the outgoing native value into primitive data.

to_internal_value(data)¶: Transform the incoming primitive data into a native value.

class lookupapi.serializers.FetchParametersSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serialise fetch parameters from a query string.

class lookupapi.serializers.SearchParametersSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serialise search parameters from a query string.

class lookupapi.serializers.InstitutionListParametersSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serialise parameters the for the institution list endpoing.

class lookupapi.serializers.AttributeSchemeSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisAttributeScheme.

class lookupapi.serializers.PersonHyperlink(view_name=None, **kwargs)¶

A field which can construct the appropriate link to a Person resource.

get_url(obj, view_name, request, format)¶

Given an object, return the URL that hyperlinks to the object.

May raise a NoReverseMatch if the view_name and lookup_field attributes are not configured to correctly match the URL conf.

class lookupapi.serializers.PersonHyperlinkSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Hyperlink-only serializer for IbisPerson objects.

class lookupapi.serializers.GroupHyperlinkSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Hyperlink-only serializer for IbisGroup objects.

class lookupapi.serializers.InstitutionHyperlinkSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Hyperlink-only serializer for IbisInstitution objects.

class lookupapi.serializers.IdentifierSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisIdentifier objects.

class lookupapi.serializers.PersonSummarySerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisPerson objects.

class lookupapi.serializers.GroupSummarySerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Summary serializer for IbisGroup objects.

class lookupapi.serializers.InstitutionSummarySerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Summary serializer for IbisInstitution.

class lookupapi.serializers.AttributeSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisAttribute objects.

class lookupapi.serializers.ContactPhoneNumberSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisContactPhoneNumber.

class lookupapi.serializers.ContactWebPageSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisContactWebPage.

class lookupapi.serializers.ContactRowSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisContactRow.

class lookupapi.serializers.InstitutionSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisInstitution.

class lookupapi.serializers.GroupSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisGroup.

class lookupapi.serializers.PersonSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for IbisPerson.

class lookupapi.serializers.PersonListResultsSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for person list results.

class lookupapi.serializers.AttributeSchemeListSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for attribute scheme lists.

class lookupapi.serializers.InstitutionListResultsSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Serializer for person list results.

class lookupapi.serializers.HealthSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)¶: Health check response.

Authentication and permissions¶

OAuth2 token-based permissions for Django REST Framework views.

class lookupapi.permissions.HasScopesPermission¶

Django REST framework permission which requires that the scopes granted to an OAuth2 token are a superset of those required for the view. The requires scopes are specified by the required_scopes attribute of the view class.

has_permission(request, view)¶: Return True if permission is granted, False otherwise.

Extensions to drf-yasg¶

Extensions to drf-yasg.

class lookupapi.inspectors.SwaggerAutoSchema(view, path, method, components, request, overrides)¶

An extension to the drf_yasg.inspectors.SwaggerAutoSchema class which knows about a few more Operation properties.

extra_properties = ['security']¶: Additional properties which may be set on operations. Prefix the properties with operation_ and pass them as additional keyword arguments to swagger_auto_schema().

get_operation(*args, **kwargs)¶

Get an Operation for the given API endpoint (path, method). This includes query, body parameters and response schemas.

Parameters:	operation_keys (tuple[str]) – an array of keys describing the hierarchical layout of this view in the API; e.g. `('snippets', 'list')`, `('snippets', 'retrieve')`, etc.
Return type:	openapi.Operation

Accessing the Lookup API¶

Convenience functions for accessing Ibis (aka “Lookup”) APIs.

lookupapi.ibis.get_connection()¶: Return an IbisClientConnection instance based upon the current settings.

See also

The defaultsettings module.

lookupapi.ibis.get_person_methods(connection=None)¶

Return a PersonMethods instance for the specified IbisClientConnection. If the connection is None then get_connection() is used to get a connection.

The returned instance has all of its callable attributes decorated with the ibis_exception_wrapper() decorator.

lookupapi.ibis.get_group_methods(connection=None)¶

Return a GroupMethods instance for the specified IbisClientConnection. If the connection is None then get_connection() is used to get a connection.

The returned instance has all of its callable attributes decorated with the ibis_exception_wrapper() decorator.

lookupapi.ibis.get_institution_methods(connection=None)¶

Return a InstitutionMethods instance for the specified IbisClientConnection. If the connection is None then get_connection() is used to get a connection.

The returned instance has all of its callable attributes decorated with the ibis_exception_wrapper() decorator.

exception lookupapi.ibis.IbisAPIException(ibis_exception)¶

A custom Django REST Framework APIException sub-class which marshals an IbisException into a form the DRF can understand.

get_full_details()¶

Return both the message & code parts of the error details.

Eg. {“name”: [{“message”: “This field is required.”, “code”: “required”}]}

lookupapi.ibis.ibis_exception_wrapper(f)¶: Function or method decorator which intercepts IbisException errors and re-raises them as IbisAPIException instances.

Default URL routing¶

The default URL mapping for lookupapi can be added to the global URL configuration in the following way:

from django.urls import include

# ...

urlpatterns = [
    # ...
    path('', include('lookupapi.urls')),
    # ...
]

lookupapi.urls.schema_view¶: alias of drf_yasg.views.get_schema_view.<locals>.SchemaView

Application configuration¶

Django application configuration for lookupapi.

class lookupapi.apps.LookupAPIConfig(app_name, app_module)¶

Configuration for lookupapi.

name = 'lookupapi'¶: The short name for this application.

verbose_name = 'Lookup REST-ful API proxy'¶: The human-readable verbose name for this application.

ready()¶: Perform application initialisation once the Django platform has been initialised.

The lookupapi application ships with some custom system checks which ensure that the LOOKUP_API_OAUTH2_... settings have non-default values. These system checks are registered by the LookupAPIConfig class’s ready() method.