# Router refactoring in 0.21

## Rationale

First generation (v1) of router has mapped `(method, path)` pair to web-handler. Mapping is named route. Routes used to have unique names if any.

The main mistake with the design is coupling the route to `(method, path)` pair while really URL construction operates with resources (location is a synonym). HTTP method is not part of URI but applied on sending HTTP request only.

Having different route names for the same path is confusing. Moreover named routes constructed for the same path should have unique non overlapping names which is cumbersome is certain situations.

From other side sometimes it’s desirable to bind several HTTP methods to the same web handler. For v1 router it can be solved by passing ‘*’ as HTTP method. Class based views require ‘*’ method also usually.

## Implementation

The change introduces resource as first class citizen:

    resource = router.add_resource('/path/{to}', name='name')

Resource has a path (dynamic or constant) and optional name.

The name is unique in router context.

Resource has routes.

Route corresponds to HTTP method and web-handler for the method:

    route = resource.add_route('GET', handler)

User still may use wildcard for accepting all HTTP methods (maybe we will add something like `resource.add_wildcard(handler)` later).

Since names belongs to resources now `app.router['name']` returns a resource instance instead of `aiohttp.web.AbstractRoute`.

resource has `.url()` method, so `app.router['name'].url(parts={'a': 'b'}, query={'arg': 'param'})` still works as usual.

The change allows to rewrite static file handling and implement nested applications as well.

Decoupling of HTTP location and HTTP method makes life easier.

## Backward compatibility

The refactoring is 99% compatible with previous implementation.

99% means all example and the most of current code works without modifications but we have subtle API backward incompatibles.

`app.router['name']` returns a `aiohttp.web.AbstractResource` instance instead of `aiohttp.web.AbstractRoute` but resource has the same `resource.url(...)` most useful method, so end user should feel no difference.

`route.match(...)` is not supported anymore, use `aiohttp.web.AbstractResource.resolve()` instead.

`app.router.add_route(method, path, handler, name='name')` now is just shortcut for:

    resource = app.router.add_resource(path, name=name)
    route = resource.add_route(method, handler)
    return route

`app.router.register_route(...)` is still supported, it creates `aiohttp.web.ResourceAdapter` for every call (but it’s deprecated now).