Router¶
Guillotina uses asgi
for it’s webserver. In order to route requests against
Guillotina’s traversal url structure, Guillotina provides it’s own router
that does traversal: guillotina.traversal.router
.
How URLs are routed¶
Guillotina’s content is structured like a file system. Objects are routed to
URL paths. HTTP verbs are provided against those objects on those paths.
Additional services(or views depending on terminology) are provided with
URL path parts that start with @
, for example, the @move
endpoint.
Route matching¶
With Guillotina, you can also route custom sub paths off a registered service. Guillotina is primarily for routing objects to urls; however, this feature is used to provide additional parameters to the service.
An example of where this is used is for file services: /db/container/item/@upload/file
.
Registering custom route parts¶
from guillotina import configure
@configure.service(
method='GET', permission='guillotina.AccessContent',
name='@match/{foo}/{bar}')
async def matching_service(context, request):
return request.matchdict # will return {'foo': 'foo', 'bar': 'bar'}
Some caveats need to be considered when mixing in routing:
- matches are only done when traversal misses
- there are limits to the variability of the route scheme you use. For example
@foobar/{one}/{two}
and@foobar/one/two
will be converted into the same service registration; however, the former will match against variable paths and the later will only match@foobar/one/two
. So you might run into restrictions quickly if you’re trying to do complex routing.
Providing your own router¶
Guillotina allows you to provide your own customized router using the router
settings.
Here is an example router that provides /v1
and /v2
type url structure:
from guillotina import configure
from guillotina.content import Resource
from guillotina.interfaces import IContainer
from guillotina.interfaces import IDefaultLayer
from guillotina.interfaces import IRequest
from guillotina.interfaces import IResource
from guillotina.traversal import TraversalRouter
from guillotina.traversal import traverse
from zope.interface import alsoProvides
class IV1Layer(IDefaultLayer):
pass
class IV2Layer(IDefaultLayer):
pass
@configure.service(method='GET', name='@foobar',
permission='guillotina.AccessContent',
layer=IV1Layer)
async def v1_service(context, request):
return {
'version': '1'
}
@configure.service(method='GET', name='@foobar',
permission='guillotina.AccessContent',
layer=IV2Layer)
async def v2_service(context, request):
return {
'version': '2'
}
@configure.contenttype(type_name="VersionRouteSegment")
class VersionRouteSegment(Resource):
type_name = 'VersionRouteSegment'
def __init__(self, name, parent):
super().__init__()
self.__name__ = self.id = name
self.__parent__ = parent
class MyRouter(TraversalRouter):
async def traverse(self, request: IRequest) -> IResource:
resource, tail = await super().traverse(request)
if len(tail) > 0 and tail[0] in ('v1', 'v2') and IContainer.providedBy(resource):
segment = VersionRouteSegment(tail[0], resource)
if tail[0] == 'v1':
alsoProvides(request, IV1Layer)
elif tail[0] == 'v2':
alsoProvides(request, IV2Layer)
if len(tail) > 1:
# finish traversal from here
return await traverse(request, segment, tail[1:])
else:
resource = segment
tail = tail[1:]
return resource, tail
app_settings = {
# provide custom application settings here...
'router': MyRouter
}