Routing

Routing

Routing refers to the definition of application end points (URIs) and how they respond to client requests.

The following code is an example of a very basic route.

import Blackfish

let app = BlackfishApp()

// respond with "hello world" when a GET request is made to the homepage
app.get("/") { request, response in
  response.send(text: "hello world");
}

Blackfish supports the following routing methods that correspond to HTTP methods: get, post, put, patch, delete

Route Methods

A route method is derived from one of the HTTP methods, and is attached to an instance of the Blackfish class.

The following code is an example of routes that are defined for the GET and the POST methods to the root of the app.

// GET method route
app.get("/") { request, response in
  response.send(text: "GET request to the homepage")
}

// POST method route
app.post("/") { request, response in
  response.send(text: "POST request to the homepage")
}

There is a special routing method, app.all(), which is not derived from any HTTP method. This method is used for loading middleware functions at a path for all request methods.

In the following example, the handler will be executed for requests to “/secret” whether you are using GET, POST, PUT, DELETE, or any other HTTP request method that is supported in the http module.

app.all("/secret") { request, response in
  print("Accessing the secret section ...")
}

Route paths

Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, with the intention of adding string patterns in the future.

Here are some examples of route paths based on strings.

This route path will match requests to the root route, /.

app.get("/") { request, response in
  response.send(text: "root")
}

This route path will match requests to /about.

app.get("/about") { request, response in
  response.send(text: "about")
}

This route path will match requests to /random.text.

app.get("/random.text") { request, response in
  response.send(text: "random.text")
}

Router

Use the Router class to create modular, mountable route handlers. A Router instance is a complete middleware and routing system; for this reason, it is often referred to as a “mini-app”.

The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app.

Create a router file named Birds.swift in the Sources directory, with the following content:

Birds.swift

import Blackfish()

func createBirdsRouter() -> Router {
    let router = Router()

    router.get("/") { request, response in
        response.send(text: "Birds home page")
    }

    router.get("/about") { request, response in
        response.send(text: "About birds")
    }

    return router
}

Then, call the function in your main.swift file and assign the router to a path

main.swift

let birdsRouter = createBirdsRouter()

app.use(path: "/birds", router: router)

The app will now be able to handle requests to /birds and /birds/about.

Controller

You can also create Controller objects that can be used to manage multiple routes.

To create a custom controller, you must inherit from the Controller protocol, and implement the routes function:

WhaleController.swift

import Blackfish

class WhaleController: Controller {

   func routes(router: Router) {
        router.get("/", handler: index)
        router.post("/about", handler: about)
    }
    
    // Variable Handler
    var index: Route.Handler {
        return { request, response in
            response.send(text: "Whales Home")
        }
    }
    
    // Function handler
    func about(request: Request, response: Response) {
        response.send(text: "About Whales")
    }
}

Handlers can be either closures or functions that take a Request and Response as their parameters.

Now, in your main.swift file, you can add the controller to the app

main.swift

let whaleController = WhaleController()

app.use(path: "/whales", controller: whaleController)

The app will now be able to handle requests to /whales and /whales/about.