REST API helpers¶
There are a number of helpers that make building out the REST API easier.
Resource paths¶
For example, most resources don’t have to worry about where they are rooted. They only need to know where they are relative to the root URI, and this function can return them the full path to the resource.
>>> from mailman.rest.helpers import path_to
>>> print(path_to('system'))
http://localhost:9001/3.0/system
Parameters like the scheme
, host
, port
, and API version number can
be set in the configuration file.
>>> config.push('helpers', """
... [webservice]
... hostname: geddy
... port: 2112
... use_https: yes
... api_version: 4.2
... """)
>>> cleanups.append((config.pop, 'helpers'))
>>> print(path_to('system'))
https://geddy:2112/4.2/system
Etags¶
HTTP etags are a way for clients to decide whether their copy of a resource
has changed or not. Mailman’s REST API calculates this in a cheap and dirty
way. Pass in the dictionary representing the resource and that dictionary
gets modified to contain the etag under the http_etag
key.
>>> from mailman.rest.helpers import etag
>>> resource = dict(geddy='bass', alex='guitar', neil='drums')
>>> json_data = etag(resource)
>>> print(resource['http_etag'])
"6929ecfbda2282980a4818fb75f82e812077f77a"
For convenience, the etag function also returns the JSON representation of the dictionary after tagging, since that’s almost always what you want.
>>> import json
>>> data = json.loads(json_data)
# This is pretty close to what we want, so it's convenient to use.
>>> dump_msgdata(data)
alex : guitar
geddy : bass
http_etag: "6929ecfbda2282980a4818fb75f82e812077f77a"
neil : drums
POST and PUT unpacking¶
Another helper unpacks POST
and PUT
request variables, validating and
converting their values.
>>> from mailman.rest.validator import Validator
>>> validator = Validator(one=int, two=str, three=bool)
>>> class FakeRequest:
... params = None
>>> FakeRequest.params = dict(one='1', two='two', three='yes')
On valid input, the validator can be used as a **keyword
argument.
>>> def print_request(one, two, three):
... print(repr(one), repr(two), repr(three))
>>> print_request(**validator(FakeRequest))
1 'two' True
On invalid input, an exception is raised.
>>> FakeRequest.params['one'] = 'hello'
>>> print_request(**validator(FakeRequest))
Traceback (most recent call last):
...
ValueError: Cannot convert parameters: one
On missing input, an exception is raised.
>>> del FakeRequest.params['one']
>>> print_request(**validator(FakeRequest))
Traceback (most recent call last):
...
ValueError: Missing parameters: one
If more than one key is missing, it will be reflected in the error message.
>>> del FakeRequest.params['two']
>>> print_request(**validator(FakeRequest))
Traceback (most recent call last):
...
ValueError: Missing parameters: one, two
Extra keys are also not allowed.
>>> FakeRequest.params = dict(one='1', two='two', three='yes',
... four='', five='')
>>> print_request(**validator(FakeRequest))
Traceback (most recent call last):
...
ValueError: Unexpected parameters: five, four
However, if optional keys are missing, it’s okay.
>>> validator = Validator(one=int, two=str, three=bool,
... four=int, five=int,
... _optional=('four', 'five'))
>>> FakeRequest.params = dict(one='1', two='two', three='yes',
... four='4', five='5')
>>> def print_request(one, two, three, four=None, five=None):
... print(repr(one), repr(two), repr(three), repr(four), repr(five))
>>> print_request(**validator(FakeRequest))
1 'two' True 4 5
>>> del FakeRequest.params['four']
>>> print_request(**validator(FakeRequest))
1 'two' True None 5
>>> del FakeRequest.params['five']
>>> print_request(**validator(FakeRequest))
1 'two' True None None
But if the optional values are present, they must of course also be valid.
>>> FakeRequest.params = dict(one='1', two='two', three='yes',
... four='no', five='maybe')
>>> print_request(**validator(FakeRequest))
Traceback (most recent call last):
...
ValueError: Cannot convert parameters: five, four
Arrays¶
Some POST
forms include more than one value for a particular key. This is
how lists and arrays are modeled. The validator does the right thing with
such form data. Specifically, when a key shows up multiple times in the form
data, a list is given to the validator.
# We can't use a normal dictionary because we'll have multiple keys, but
# the validator only wants to call .items() on the object.
>>> class MultiDict:
... def __init__(self, *params): self.values = list(params)
... def items(self): return iter(self.values)
>>> form_data = MultiDict(
... ('one', '1'),
... ('many', '3'),
... ('many', '4'),
... ('many', '5'),
... )
This is a validation function that ensures the value is a list.
>>> def must_be_list(value):
... if not isinstance(value, list):
... raise ValueError('not a list')
... return [int(item) for item in value]
This is a validation function that ensure the value is not a list.
>>> def must_be_scalar(value):
... if isinstance(value, list):
... raise ValueError('is a list')
... return int(value)
And a validator to pull it all together.
>>> validator = Validator(one=must_be_scalar, many=must_be_list)
>>> FakeRequest.params = form_data
>>> values = validator(FakeRequest)
>>> print(values['one'])
1
>>> print(values['many'])
[3, 4, 5]
The list values are guaranteed to be in the same order they show up in the form data.
>>> FakeRequest.params = MultiDict(
... ('one', '1'),
... ('many', '3'),
... ('many', '5'),
... ('many', '4'),
... )
>>> values = validator(FakeRequest)
>>> print(values['one'])
1
>>> print(values['many'])
[3, 5, 4]