When coding a web system, you have to think about an important problem, how to map urls to logic.
Openstack use routes to solve this problem.
What is routes
Routes is a python package used to map urls to program logic. Normally this is the web framework`s responsibility, so besides openstack, routes is also used in several other python web frameworks.
Quick start
>>> from routes import Mapper
>>> map = Mapper()
>>> map.connect('route_name_update_net', '/nets/{net_id}', controller='nets_controller', conditions=dict(method=['PUT']), self_defined_key='self_defined_value')
# Above code created a route named "route_name_update_net"
# It match any two component urls started with /nets
# Controller which will process the request is nets_controller
# Conditions parameter restrict the route only accept PUT request
>>> map.match('/nets/123')
{'controller': u'nets_controller', 'net_id': u'123', "self_defined_key":"self_defined_value"}
# As you can see, the url which match the route will return a dict. The dict contains the controller information and necessary var
# The self_defined_key and self_defined_value also included.
>>> print map
Route name Methods Path
route_name_update_net PUT /nets/{net_id}
>>>
Basic usage
Requirements
Some times you want to restrict the path var, you can use the requirements parameter in below ways
map.connect(R"/download/{platform:windows|mac}/{filename}")
This line restrict the platform var could only be windows or mac. You can also write it in below way
map.connect("/download/{platform}/{filename}", requirements={"platform": R"windows|mac"})
The R char here is very important. Without it you may need to double your slash in your url.
Once you restrict your route, you can try it like below:
# The platform must be windows or mac so below url match
>>> map.match('/download/windows/myfile')
{'platform': u'windows', 'filename': u'myfile'}
# The linux is not valid here so does not match
>>> map.match('/download/linux/myfile')
PATH_INFO
In WSIG env, the url information is stored in the environ dict with key PATH_INFO.
Routes treat the path_info specially. When the “path_info” variable is used at the end of the URL, Routes moves everything preceding it into the “SCRIPT_NAME” environment variable. This is useful when delegating to another WSGI application that does its own routing: the subapplication will route on the remainder of the URL rather than the entire URL
For example
>>> from routes import Mapper
>>> map=Mapper()
>>> map.connect('/classes/{path_info:.*}')
>>> map.match('/classes/students/tom')
{'path_info': 'students/tom'}
>>>
The subsequent system will see PATH_INFO: /students/tom and SCRIPT_NAME:classes. So the sub system can use its own route system.
Format extensions
Consider to design a url /neutron/networks/{network_id} which will used to access the network resource. The network can be returned in JSON format or XML format. So we can do it in routes like this:
>>> from routes import Mapper
>>> map=Mapper()
>>>
>>> map.connect('/neutron/networks/{network_id}{.format:json|xml}')
>>> map.match('/neutron/networks/123.json')
{'network_id': u'123', 'format': u'json'}
>>> map.match('/neutron/networks/123.xml')
{'network_id': u'123', 'format': u'xml'}
>>> map.match('/neutron/networks/123.html')
{'network_id': u'123.html', 'format': None}
Use the format parameter to specify the resource format
RESTful
Use routes can generate restful routes very conveniently
>>> from routes import Mapper
>>> map=Mapper()
>>> map.resource('net','nets')
>>> print map
Route name Methods Path
POST /nets.:(format)
POST /nets
formatted_nets GET /nets.:(format)
nets GET /nets
formatted_new_net GET /nets/new.:(format)
new_net GET /nets/new
PUT /nets/:(id).:(format)
PUT /nets/:(id)
DELETE /nets/:(id).:(format)
DELETE /nets/:(id)
formatted_edit_net GET /nets/:(id)/edit.:(format)
edit_net GET /nets/:(id)/edit
formatted_net GET /nets/:(id).:(format)
net GET /nets/:(id)
The first parameter is resource name also called member in RESTful
The second is the plural of resource name which is also called collection in RESTful
the resource function have several parameters and we will learn them one by one
controller
This parameter specify the controller to handle the request. For example:
>>> map=Mapper()
>>> map.resource('net','nets', controller='net_controller')
>>> map.match('/nets/123')
{'action': u'update', 'controller': u'net_controller', 'id': u'123'}
collection
This parameter add more additional urls for the collection operations. For example:
Before use the parameter the map is like below
>>> map=Mapper()
>>> map.resource('net','nets', controller='net_controller')
>>> print map
Route name Methods Path
POST /nets.:(format)
POST /nets
formatted_nets GET /nets.:(format)
nets GET /nets
formatted_new_net GET /nets/new.:(format)
new_net GET /nets/new
PUT /nets/:(id).:(format)
PUT /nets/:(id)
DELETE /nets/:(id).:(format)
DELETE /nets/:(id)
formatted_edit_net GET /nets/:(id)/edit.:(format)
edit_net GET /nets/:(id)/edit
formatted_net GET /nets/:(id).:(format)
net GET /nets/:(id)
After we add the collection parameter
>>> map.resource('net','nets', controller='net_controller', collection={'subnets':'POST'})
>>> print map
Route name Methods Path
formatted_subnets_nets POST /nets/subnets.:(format)
subnets_nets POST /nets/subnets
POST /nets.:(format)
POST /nets
formatted_nets GET /nets.:(format)
nets GET /nets
formatted_new_net GET /nets/new.:(format)
new_net GET /nets/new
PUT /nets/:(id).:(format)
PUT /nets/:(id)
DELETE /nets/:(id).:(format)
DELETE /nets/:(id)
formatted_edit_net GET /nets/:(id)/edit.:(format)
edit_net GET /nets/:(id)/edit
formatted_net GET /nets/:(id).:(format)
net GET /nets/:(id)
The collection operation can mathc /nets/subnets on POST method.
member
>>> map=Mapper()
>>> map.resource('net','nets', controller='net_controller', member={'subnets':'POST'})
>>> print map
Route name Methods Path
POST /nets.:(format)
POST /nets
formatted_nets GET /nets.:(format)
nets GET /nets
formatted_new_net GET /nets/new.:(format)
new_net GET /nets/new
PUT /nets/:(id).:(format)
PUT /nets/:(id)
formatted_subnets_net POST /nets/:(id)/subnets.:(format)
subnets_net POST /nets/:(id)/subnets
DELETE /nets/:(id).:(format)
DELETE /nets/:(id)
formatted_edit_net GET /nets/:(id)/edit.:(format)
edit_net GET /nets/:(id)/edit
formatted_net GET /nets/:(id).:(format)
net GET /nets/:(id)
After use member parameter, the member operation can match /nets/{id}/subnets
path_prefix and name_prefix
This two parameter are used together. For example:
>>> map=Mapper()
>>> map.resource("message", "messages", controller="categories", path_prefix="/category/{category_id}", name_prefix="category_")
>>> print map
Route name Methods Path
POST /category/{category_id}/messages.:(format)
POST /category/{category_id}/messages
formatted_category_messages GET /category/{category_id}/messages.:(format)
category_messages GET /category/{category_id}/messages
formatted_category_new_message GET /category/{category_id}/messages/new.:(format)
category_new_message GET /category/{category_id}/messages/new
PUT /category/{category_id}/messages/:(id).:(format)
PUT /category/{category_id}/messages/:(id)
DELETE /category/{category_id}/messages/:(id).:(format)
DELETE /category/{category_id}/messages/:(id)
formatted_category_edit_message GET /category/{category_id}/messages/:(id)/edit.:(format)
category_edit_message GET /category/{category_id}/messages/:(id)/edit
formatted_category_message GET /category/{category_id}/messages/:(id).:(format)
category_message GET /category/{category_id}/messages/:(id)
The path_prefix add a url prefix to the urls that can be matched. The name_prefix is the prefix of route name.
They actually are parent resource of message.
Parent resource
>>> from routes import Mapper
>>> map=Mapper()
>>> map.resource('location', 'locations', parent_resource=dict(member_name='region', collection_name='regions'))
>>> print map
Route name Methods Path
POST /regions/:region_id/locations.:(format)
POST /regions/:region_id/locations
formatted_region_locations GET /regions/:region_id/locations.:(format)
region_locations GET /regions/:region_id/locations
formatted_region_new_location GET /regions/:region_id/locations/new.:(format)
region_new_location GET /regions/:region_id/locations/new
PUT /regions/:region_id/locations/:(id).:(format)
PUT /regions/:region_id/locations/:(id)
DELETE /regions/:region_id/locations/:(id).:(format)
DELETE /regions/:region_id/locations/:(id)
formatted_region_edit_location GET /regions/:region_id/locations/:(id)/edit.:(format)
region_edit_location GET /regions/:region_id/locations/:(id)/edit
formatted_region_location GET /regions/:region_id/locations/:(id).:(format)
region_location GET /regions/:region_id/locations/:(id)
This is the same as path_prefix and name_prefix. The path_prefix here is /regions/{region_id} and name_prefix is region_
openstack use routes to map url to controller, so it is necessary to know about routes. Routes are came from Ruby on rails. It is rewritten in python. So docs about routes are not very clear might because the author think we should learn Ruby on rails routes first.
Submapper
submapper is a lazy way to write code. See examples below:
You want to generate a series route， they have common attributes like
controller: common_controller
action: index
path_prefix: api/v2
conditions: {'method':'GET'}
You can write the code in this way
>>> from routes import Mapper
>>> map = Mapper()
>>> with map.submapper(controller='common_controller', action='index', path_prefix='api/v2/', contidions={'method':'GET'}) as submapper:
... submapper.connect('api/v2/'+'nets', 'nets')
... submapper.connect('api/v2/'+'subnets', 'subnets')
...
>>> print map
Route name Methods Path
api/v2/nets api/v2/nets
api/v2/subnets api/v2/subnets
In this way you can put the common attributes in submapper.