---
title: Route
---

# `Wayfarer::Route`

All public functionality documented here is exposed via
`Wayfarer::Routing::DSL`.

---

### `#host(String | Regexp)`
:   Match hosts against strings or regular expressions.

    ##### Examples

    !!! example "Exact hostname string matching"

        ```ruby
        route.host "example.com"
        ```

        - [x] https://{==example.com==}
        - [x] https://{==example.com==}/foo/bar
        - [ ] https://sub.example.com
        - [ ] https://nasa.gov

    !!! example "Hostname matching with regular expression"

        ```ruby
        route.host /example.com$/
        ```

        - [x] https://{==example.com==}
        - [x] https://{==example.com==}/foo/bar
        - [x] https://{==sub.example.com==}
        - [ ] https://nasa.gov

---

### `#suffix(String)`
:   Match URL paths against exact suffixes.

    ##### Examples

    !!! example "Match only URLs with paths ending with \*.png"

        ```ruby
        route.suffix ".png"
        ```

        - [x] https://example.com/image{==.png==}
        - [ ] https://example.com/index.html
        - [ ] https://example.com

---

### `#path(String)`
:   Match URLs against their path.

    ##### Examples

    !!! example "Exact path string matching"

        ```ruby
        route.path "/users/123"
        ```

        - [x] https://example.com/{==users/123==}
        - [x] https://example.com/{==users/123==}
        - [ ] https://example.com/users
        - [ ] https://example.com

    !!! example "Root path matching"

        ```ruby
        route.path "/"
        ```

        - [x] https://example.com{==/==}
        - [ ] https://example.com
        - [ ] https://example.com/users

    !!! example "Pattern matching"

        ```ruby
        route.path "/users/:id", to: :with_params
        route.path "/contact", to: :without_params

        def with_params
          params # => { "id" => ... }
        end

        def without_params
          params # => {}
        end
        ```

        - [x] https://example.com{==/users/123==}
        - [x] https://example.com{==/contact==}
        - [ ] https://example.com
        - [ ] https://example.com/users/123/photos
        - [ ] https://example.com/contact/

---

### `#query(Hash)`
:   Match URLs against query parameters.

    ##### Examples

    !!! example "Exact parameter string matching"

        ```ruby
        route.query arg: "foo"
        ```

        - [x] https://example.com?{==arg=foo==}
        - [x] https://example.com?{==arg=foo==}&page=2
        - [ ] https://example.com?arg=123
        - [ ] https://example.com

    !!! example "Parameter regular expression matching"

        ```ruby
        route.query arg: /foo/
        ```

        - [x] https://example.com?{==arg=foo==}
        - [x] https://example.com?{==arg=foobar==}
        - [x] https://example.com?{==arg=barfoo==}&page=2
        - [ ] https://example.com?arg=123
        - [ ] https://example.com

    !!! example "Parameter integer matching"

        ```ruby
        route.query page: 5
        ```

        - [x] https://example.com?{==page=5==}
        - [x] https://example.com?arg=foo&{==page=5==}
        - [ ] https://example.com?page=3
        - [ ] https://example.com

    !!! example "Parameter range matching"

        ```ruby
        route.query page: 1..10
        ```

        - [x] https://example.com?{==page=1==}
        - [x] https://example.com?arg=foo&{==page=10==}
        - [ ] https://example.com?page=11
        - [ ] https://example.com

### `#scheme(Symbol)`
:   Match URLs by their scheme.

    ##### Examples

    !!! example "Scheme matching"

        ```ruby
        route.scheme :https
        ```

        - [x] {==https==}://example.com
        - [ ] http://example.com

### `#uri(String)`
:   Match URLs exactly.

    ##### Examples

    !!! example "URL matching"

        ```ruby
        route.uri "https://example.com/foo/bar?page=3"
        ```

        - [x] {==https://example.com/foo/bar?page=3==}