Parametrization

The API definitions can be parametrized for convenient run-time use. The parametrization function accepts an optional context argument that is simply a dictionary that is used to assign values to all the named parameters found in the operations. Parameters are prefixed with the dollar sign ('$'). So it would be possible to also specify a single dynamically invoked operation for listing the rooms:

operations:
  list-rooms:
    label: List room reservations
    description: List reserved rooms
    template: roomapi
    request:
      params:
        size: $size

By passing either {"size":"single"} or {"size": "double"} as context, room size values would then be assigned:

>>> from httpreverse import parametrize
>>> api = yaml.load(yamlsource)
>>> operation = api["operations"]["list-rooms"]
>>> parametrized = parametrize(operation, context={"size":single})
>>>

More complex parametrizations are possible using the same simple mechanism:

operations:
  add-reservation:
    label: Add reservation
    description: Add a room reservation
    template: roomapi
    request:
      method: POST
      body: {"size": $roomsize, "customers": $customers}

The context would then have to include both the room size and occupants, ie. {"roomsize":"double", "customers":["John Doe", "Jane Doe"]}.

Consult the YAML documentation for more on what kind of types and data structures are possible to express.

Note that for structured data types such as mappings, you need to indicate what they should be marshaled to. Please see the docs on structured parameter marshaling for details.