Allow additional URL parameters to HyperlinkRelated

[multimeric]

This is basically a reiteration of #54.

I have an API where a report conceptually has multiple samples. Thus, the sample URL has two parameters, e.g. (my example uses Flask-Restful):

restful.add_resource(Sample, '/reports/<int:report_id>/samples/<int:sample_id>')

And then the marshmallow schema uses HyperlinkRelated:

class ReportSchema(ModelSchema):
    samples = ma.List(ma.HyperlinkRelated('rest_api.sample', url_key='sample_id'))

This will then fail with:

werkzeug.routing.BuildError: Could not build url for endpoint 'rest_api.sample' with values ['sample_id']. Did you forget to specify values ['report_id']?

Notably, this also doesn't work with URLFor(), because that can only take attributes from the parent object, not the relationship objects:

class ReportSchema(ModelSchema):
    samples = ma.List(ma.URLFor("rest_api.sample", sample_id='<sample_id>', report_id='<report_id>'))

AttributeError: 'sample_id' is not a valid attribute of <Report(21)>

---

What we need is a dictionary that maps URL parameters to fields on the related object, e.g.

class ReportSchema(ModelSchema):
    samples = ma.List(ma.HyperlinkRelated('rest_api.sample', url_map={
        'sample_id': 'sample_id',
        'report_id': 'report_id'
    }))

In this case, the url_map field means "fill in the missing segments of the URL by using fields from the relationship object".

[multimeric]

Incidentally, my current solution to this problem is making a new custom field, as in this gist: https://gist.github.com/TMiguelT/2e710b50dfccc6cdb348f398627bc0ee.

You use it like this:

class ReportSchema(ModelSchema):
    samples = ResourceHyperlink(endpoint='rest_api.sample', url_args=[
        'report_id',
        'sample_id'
    ])

Basically you can either provide url_args as a list of keys that we take directly from the related model to apply to the URL (in this case, report_id and sample_id), or you can make that a dictionary that maps URL segments to model properties as I explained above.

I also require that you pass in an endpoint rather than a resource object, just because there will be issues with circular dependencies if you import the resources from the schema and then import the schema in the resources in order to dump/load. The endpoint string for a given resource will be module.path.resource_name, although you can override it with the restful.add_resource() function.

I also recommend that you prefetch the related objects for this field, using query.options(joinedload(user_models.User.roles)), since my class makes use of the related object. If you don't do this, the efficiency will be much worse