Metadata Modules

Metadata modules provide access to metadata about the API. The pyramid_jsonapi.metadata class is responsible for loading the modules and setting up routes and views under /metadata (by default - see settings).

Built-in Modules

The metadata_modules configuration option lists modules which are to be loaded (see settings). If this list is empty, no modules will be loaded.

Note: Some modules are required for core functionality - for example schema validation requires the jsonschema module.

The default setting for this option includes the following modules:

• pyramid_jsonapi.metadata.JSONSchema package
  • Module contents
    • Configuration
    • Endpoint View
• pyramid_jsonapi.metadata.OpenAPI package
  • Module contents
    • Configuration

Custom Modules

As well as the built-in modules it is possible to write new metadata modules and add them to the metadata_modules list (space or newline separated).

Note - if modifying the metadata_modules list, you will need to explicitly include any of the ones provided with the project you wish to keep active.

Requirements

Any modules must follow these rules in order to work properly:

• The module MUST contain a class with the same name as the package.

• The class MUST expect to be passed a reference to the pyramid_jsonapi.JSONAPI instance as the first argument.

• The class MAY contain a views attribute, which contains a list of pyramid_jsonapi.metadata.VIEWS namedtuple instances. These are mapped onto a pyramid.config.add_view() call. (Views are optional - methods may exist in modules to be called ‘internally by other methods/modules, rather than being web-facing).

For example, to add a custom metadata module called Foo, you need to do the following:

1. Create a Foo package, and ensure it is available to be imported in the python environment.

2. In Foo/__init__.py add the following:

class Foo():

    def __init__(self, api):

        self.views = [
            pyramid_jsonapi.metadata.VIEWS(
                attr='generate_dict', # The method to associate with the view
                route_name='',  # The relative route name to attach this method to (defaults to /metadata/Foo)
                request_method='', # The http request method (defaults to GET)
                renderer=''  # The pyramid renderer (defaults to json)
            ),
            pyramid_jsonapi.metadata.VIEWS(
                attr='generate_string',
                route_name='resource/{endpoint}',
                request_method='GET',
                renderer='string'
            ),
        ]

    def generate_dict(self, request):
        return {'foo': 'bar'}

    def generate_string(self, request):
       return "foo: {}".format(request.matchdict['endpoint'])

Note the use of the Route pattern syntax in the second example would result in generate_string() being called for route /metadata/Foo/resource/baz with endpoint set to baz.