Documented JsonPayload use

Here, ``MyRouteAPI`` is a web API plugin class, subclassing :py:class:`openflexure_microscope.api.v1.views.MicroscopeViewPlugin`. If your plugin package were named ``mypluginpackage``, an API route would be automatically added at ``/api/v1/plugin/mypluginpackage/myplugin``.

Parsing JSON from HTTP POST requests

++++++++++++++++++++++++++++++++++++

To ease obtaining values from a JSON payload attached to an HTTP POST request, you can use the :py:class:`openflexure_microscope.api.utilities.JsonPayload` class. This allows parameters to be extracted by their key, with a default value supplied to avoid errors associated with nonexistent keys. Additionally, a converter function may be passed, used in the following examples to convert the type of a value. In principle, however, you can pass any single-argument function and it will apply that function to the value, if it exists.

.. code-block:: python

    ...

    class MyRouteAPI(MicroscopeViewPlugin):

        def post(self):

            # Get payload JSON from request

            payload = JsonPayload(request)

            # Try to find value associated with 'my_string' key.

            # If that key doesn't exist in the payload, return '' instead.

            # If a value does exist, convert it to a string, regardless of its original type.

            new_plugin_string = payload.param('my_string', default='', convert=str)

            ...

For more details, see the documentation for :py:class:`openflexure_microscope.api.utilities.JsonPayload`.

The MicroscopeViewPlugin class

++++++++++++++++++++++++++++++

        def post(self):

            # Get payload JSON, and extract a specific value

            state = parse_payload(request)

            my_payload_value = get_from_payload(state, 'my_payload_key')

            payload = JsonPayload(request)

            my_payload_value = payload.param('my_payload_key')

            ...

Accessing the microscope

    from openflexure_microscope.plugins import MicroscopePlugin

    from openflexure_microscope.api.v1.views import MicroscopeViewPlugin

    from openflexure_microscope.api.utilities import parse_payload, get_from_payload

    from openflexure_microscope.api.utilities import JsonPayload

    from flask import request, Response, escape

            Method to call when an HTTP POST request is made. 

            Assumes request will include a JSON payload.

            """

            # Get payload JSON as a dictionary

            state = parse_payload(request)

            # Get payload JSON

            payload = JsonPayload(request)

            # Extract a value from the JSON key 'plugin_string'. If no value is given, default to None

            new_plugin_string = get_from_payload(state, 'plugin_string', default=None)

            # Extract a value from the JSON key 'plugin_string', and convert to a string. If no value is given, default to empty.

            new_plugin_string = payload.param('plugin_string', default='', convert=str)

            if new_plugin_string:  # If not None or empty

                # Set microscope attribute to the specified string