Skip to main content

REST tools in python - common code for client and server

Project description

PyPI GitHub release (latest by date including pre-releases) PyPI - License Lines of code GitHub issues GitHub pull requests

rest-tools

This project contains REST tools in python, as common code for multiple other projects under https://github.com/WIPACrepo.

All code uses python asyncio, so is fully asyncronous.

Note that both the client and server assume starting the asyncio loop happens elsewhere - they do not start the loop themselves.

Client

A REST API client exists under rest_tools.client. Use as:

from rest_tools.client import RestClient

api = RestClient('http://my.site.here/api', token='XXXX')
ret = await api.request('GET', '/fruits/apple')
ret = await api.request('POST', '/fruits', {'name': 'banana'})

There are several variations of the client for OAuth2/OpenID support:

  • OpenIDRestClient : A child of RestClient that supports OAuth2 token refresh using the OpenID Connect Discovery protocol for an authentication server.

  • ClientCredentialsAuth : Uses OpenIDRestClient in combination with OAuth2 client credentials (client ID and secret) for service-based auth. Use this for long-lived services that need to perform REST API calls.

  • DeviceGrantAuth / SavedDeviceGrantAuth : Uses OpenIDRestClient to perform a "device" login for a user. Use this for user-based terminal applications that need to perform REST API calls. The SavedDeviceGrantAuth can save the refresh token to disk, allowing repeated application sessions without having to log in again.

Server

A REST API server exists under rest_tools.server. Use as:

import asyncio
from rest_tools.server import RestServer, RestHandler

class Fruits(RestHandler):
    def post(self):
        # handle a new fruit
        self.write({})

server = RestServer()
server.add_route('/fruits', Fruits)
server.startup(address='my.site.here', port=8080)
asyncio.get_event_loop().run_forever()

The server uses Tornado to handle HTTP connections. It is recommended to use Apache or Nginx as a front-facing proxy, to handle TLS sessions and non-standard HTTP requests in production.

Handling Arguments Server-side

server.ArgumentHandler is a robust wrapper around argparse.ArgumentParser, extended for use in handling REST arguments, both query arguments and JSON-encoded body arguments. The intended design of this class is to follow the argparse pattern as closely as possible.

from rest_tools.server import RestHandler, ArgumentHandler, ArgumentSource

class Fruits(RestHandler):

    def get(self):
        argo = ArgumentHandler(ArgumentSource.QUERY_ARGUMENTS, self)

        argo.add_argument('name', type=str)  # de-facto required
        argo.add_argument('alias', dest='other_names', type=str, nargs='*', default=[])  # list

        argo.add_argument('is-citrus', type=bool, default=False)
        argo.add_argument('amount', type=float, required=True)

        args = argo.parse_args()

        fruit = get_fruit(args.name, args.other_names, args.is_citrus, args.amount)

        ...

    def post(self):
        argo = ArgumentHandler(ArgumentSource.JSON_BODY_ARGUMENTS, self)

        argo.add_argument('name', type=str)  # de-facto required
        argo.add_argument('other-names', type=list, default=[])

        argo.add_argument('supply', type=dict, required=True)

        def _origin(val):
            try:
                return {'USA': 'United States of America', 'MEX': 'Mexico'}[val]
            except KeyError:
                # raise a ValueError or TypeError to propagate a 400 Error
                raise ValueError('Invalid origin')

        argo.add_argument('country_code', dest='origin', type=_origin, required=True)

        args = argo.parse_args()

        add_to_basket(args.name, args.other_names, args.supply, args.origin)

        ...

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wipac-rest-tools-1.6.0.tar.gz (30.5 kB view hashes)

Uploaded Source

Built Distribution

wipac_rest_tools-1.6.0-py3-none-any.whl (35.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page