aah Routing

aah supports domains and subdomains seamlessly. It provides route URL lookup by route name effectively.

The router is optimized for high performance and a small memory footprint. It scales well with very long paths and a large number of routes. Radix tree structure is used for efficient matching.

aah internally uses customized version of httprouter, developed by @julienschmidt.

Table of Contents

• Highlights
• Route Definitions
• Route Constraints
  • Supported Constraints

Highlights

• URI Parameters - Give path segment a name and access it as action method parameters.
• Perfect for RESTful APIs - Build sensible, hierarchical RESTful APIs. Router has builtin native support for OPTIONS requests and 405 Method Not Allowed replies.
• Only explicit matches - a request can only match exactly one or no route. As a result, there are also no unintended matches, which makes it great for SEO and improves the user experience.
• Stop caring about trailing slashes - Choose the URL style you like, the router automatically redirects the client if a trailing slash is missing or if there is one extra. Of course, it does only if the new path has a controller action. Behavior could be disabled at domain level using redirect_trailing_slash = false in the routes config.
• Path auto-correction - Besides detecting the missing or additional trailing slash at no extra cost, the router can also fix wrong cases and remove superfluous path elements (like ../ or //). Is CAPTAIN CAPS LOCK one of your users? Router can help user by making a case-insensitive look-up and by redirecting to the correct URL.
• Zero Garbage - The matching and dispatching process generates zero bytes of garbage. In fact, the only heap allocations that are made, is by building the slice of the key-value pairs for path parameters. If the request path contains no parameters, not even a single heap allocation is necessary.

Route Definitions

aah routes.conf is composed of four major config sections, such as domains, domain, static routes and application routes.

Learn routes configuration attributes and its purpose.

# -----------------------------------------------------------------------------
# app name - Application Routes Configuration
#
# Refer documentation to explore and configure routes.
# Doc: https://docs.aahframework.org/routing.html
# -----------------------------------------------------------------------------
domains {
  # Choose a `unique keyname` to define domain section and its configuration.
  # Tip: Use app name, domain name address, port no values to create a domain key.
  #
  # Examples: aahframework { ... }, docs_aahframework { ... }
  domain_key_name {

    #
    # Domain configurations - host, port and CORS, for example.
    #

    # Static files Routes Configuration
    # Optional section- API and WebSocket apps, as examples
    static {
      # ...
    }

    # Routes Configuration
    routes {

      # domain routes comes here

    } # end - routes

  } # end - domain configurations



  # Choose a `unique keyname` to define domain section and its configuration.
  # Tip: Use app name, domain name address, port no values to create a domain key.
  #
  # Examples: aahframework { ... }, docs_aahframework { ... }
  domain_key_name {

    #
    # Domain configurations - host, port and CORS, for example.
    #

    # Static files Routes Configuration
    # Optional section- API and WebSocket apps, as examples
    static {
      # ...
    }

    # Routes Configuration
    routes {

      # domain routes comes here

    } # end - routes

  } # end - domain configurations

} # end - all application domains

Route Constraints

Route constraints give the capability to restrict/validate route parameters (aka URI parameters) before the request sent to controller action.

# Syntax
:parameterName[constraints]

Examples

# Examples of route path parameters with constraints

#------------------------------------------------------------------------------
# Example - Data type constraints are implicit in aah
# Path              : /v1/users/:id
# Controller Action : func (u *UserController) Info(id int) { .. }

# Requests
/v1/users/10001           => pass, would reach controller action
/v1/users/myname          => fail, 400 BadRequest

#------------------------------------------------------------------------------
# Example - ISBN 13 route parameter constraint
# Path              : /v1/books/:isbn[isbn13]/excerpt
# Controller Action : func (b *BookController) Excerpt(isbn string) { .. }

# Requests - ISBN numbers taken from https://www.isbn-13.info/example
/v1/books/978-1-56619-909-4/excerpt   => pass, would reach controller action
/v1/books/9781566199094/excerpt       => pass, would reach controller action
/v1/books/1-56619-909-3/excerpt       => fail, 400 BadRequest
/v1/books/1566199093/excerpt          => fail, 400 BadRequest
/v1/books/dshgdshgdsjhgdshg/excerpt   => fail, 400 BadRequest

#------------------------------------------------------------------------------
# Example - oneof and alpha route parameter constraints
# Path              : /v1/temperature/:scale[oneof=celsius fahrenheit,alpha]
# Controller Action : func (w *WeatherController) Temperature(scale string) { .. }

# Requests
/v1/temperature/fahrenheit      => pass, would reach controller action
/v1/temperature/celsius         => pass, would reach controller action
/v1/temperature/3463543         => fail, 400 BadRequest
/v1/temperature/blabla          => fail, 400 BadRequest
#------------------------------------------------------------------------------

Supported Constraints