swh.web.api package


swh.web.api.apidoc module

exception swh.web.api.apidoc.APIDocException[source]

Bases: Exception

Custom exception to signal errors in the use of the APIDoc decorators

class swh.web.api.apidoc.api_doc(route, noargs=False, tags=[], handle_response=False, api_version='1')[source]

Bases: object

Decorate an API function to register it in the API doc route index and create the corresponding DRF route.

  • route (str) – documentation page’s route
  • noargs (boolean) – set to True if the route has no arguments, and its result should be displayed anytime its documentation is requested. Default to False
  • tags (list) –

    Further information on api endpoints. Two values are possibly expected:

    • hidden: remove the entry points from the listing
    • upcoming: display the entry point but it is not followable
  • handle_response (boolean) – indicate if the decorated function takes care of creating the HTTP response or delegates that task to the apiresponse module
  • api_version (str) – api version string

Build documentation data for the decorated api endpoint function

swh.web.api.apiresponse module

Add Link header in returned value results.

  • rv (dict) –

    dictionary with keys:

    • headers: potential headers with ‘link-next’ and ‘link-prev’ keys
    • results: containing the result to return
  • options (dict) – the initial dict to update with result if any

dictionary with optional keys ‘link-next’ and ‘link-prev’

Return type:


swh.web.api.apiresponse.filter_by_fields(request, data)[source]

Extract a request parameter ‘fields’ if it exists to permit the filtering on the data dict’s keys.

If such field is not provided, returns the data as is.


Transform an eventual returned value with multiple layer of information with only what’s necessary.

If the returned value rv contains the ‘results’ key, this is the associated value which is returned.

Otherwise, return the initial dict without the potential ‘headers’ key.

swh.web.api.apiresponse.make_api_response(request, data, doc_data={}, options={})[source]

Generates an API response based on the requested mimetype.

  • request – a DRF Request object
  • data – raw data to return in the API response
  • doc_data – documentation data for HTML response
  • options – optional data that can be used to generate the response

a DRF Response a object

swh.web.api.apiresponse.error_response(request, error, doc_data)[source]

Private function to create a custom error response.

  • request – a DRF Request object
  • error – the exception that caused the error
  • doc_data – documentation data for HTML response

swh.web.api.apiurls module

class swh.web.api.apiurls.APIUrls[source]

Bases: swh.web.common.urlsindex.UrlsIndex

Class to manage API documentation URLs.

  • Indexes all routes documented using apidoc’s decorators.
  • Tracks endpoint/request processing method relationships for use in generating related urls in API documentation
scope = 'api'
classmethod get_app_endpoints()[source]
classmethod add_route(route, docstring, **kwargs)[source]

Add a route to the self-documenting API reference

class swh.web.api.apiurls.api_route(url_pattern=None, view_name=None, methods=['GET', 'HEAD', 'OPTIONS'], throttle_scope='swh_api', api_version='1')[source]

Bases: object

Decorator to ease the registration of an API endpoint using the Django REST Framework.

  • url_pattern – the url pattern used by DRF to identify the API route
  • view_name – the name of the API view associated to the route used to reverse the url
  • methods – array of HTTP methods supported by the API route

swh.web.api.renderers module

class swh.web.api.renderers.YAMLRenderer[source]

Bases: rest_framework.renderers.BaseRenderer

Renderer which serializes to YAML.

media_type = 'application/yaml'
format = 'yaml'
charset = 'utf-8'
ensure_ascii = False
default_flow_style = False
render(data, accepted_media_type=None, renderer_context=None)[source]

Renders data into serialized YAML.

swh.web.api.urls module

swh.web.api.utils module

swh.web.api.utils.filter_field_keys(data, field_keys)[source]

Given an object instance (directory or list), and a csv field keys to filter on.

Return the object instance with filtered keys.

Note: Returns obj as is if it’s an instance of types not in (dictionary, list)

  • data (-) – one object (dictionary, list…) to filter.
  • field_keys (-) – csv or set of keys to filter the object on

obj filtered on field_keys


Map a person (person, committer, tagger, etc…) to a string.


Enrich an object (revision, release) with link to the ‘target’ of type ‘target_type’.

  • object – An object with target and target_type keys
  • release, revision) ((e.g.) –

Object enriched with target_url pointing to the right swh.web.ui.api urls for the pointing object (revision, release, content, directory)


Enrich an object (revision, release) with link to the ‘target’ of type ‘target_type’.

  • object – An object with target and target_type keys
  • release, revision) ((e.g.) –

Object enriched with target_url pointing to the right swh.web.ui.api urls for the pointing object (revision, release, content, directory)

swh.web.api.utils.enrich_directory(directory, context_url=None)[source]

Enrich directory with url to content or directory.


Enrich metadata endpoint with link to the upper metadata endpoint.

swh.web.api.utils.enrich_content(content, top_url=False, query_string=None)[source]
Enrich content with links to:
  • data_url: its raw data
  • filetype_url: its filetype information
  • language_url: its programming language information
  • license_url: its licensing information
  • content – dict of data associated to a swh content object
  • top_url – whether or not to include the content url in the enriched data
  • query_string – optional query string of type ‘<algo>:<hash>’ used when requesting the content, it acts as a hint for picking the same hash method when computing the url listed above

An enriched content dict filled with additional urls


Enrich revision with links where it makes sense (directory, parents). Keep track of the navigation breadcrumbs if they are specified.

Parameters:revision – the revision as a dict

Module contents