diff --git a/guide/routing.md b/guide/routing.md index 8429212c..17c8b438 100644 --- a/guide/routing.md +++ b/guide/routing.md @@ -6,19 +6,8 @@ currentMenu: guide-routing Routes in Vapor can be defined in any file that has access to your instance of `Droplet`. This is usually in the `main.swift` file. -## Basic -The most basic route includes a method, path, and closure. -```swift -drop.get("welcome") { request in - return "Hello" -} -``` - -The standard HTTP methods are available including `get`, `post`, `put`, `patch`, `delete`, and `options`. - -You can also use `any` to match all methods. ## Request diff --git a/routing/basic.md b/routing/basic.md new file mode 100644 index 00000000..a9132493 --- /dev/null +++ b/routing/basic.md @@ -0,0 +1,116 @@ +--- +currentMenu: routing-basic +--- + +# Basic Routing + +Routing is one of the most critical parts of a web framework. The router decides which requests get which responses. + +Vapor has a plethora of functionality for routing including route builders, groups, and collections. In this section, we will look at the basic of routing. + +## Register + +The most basic route includes a method, path, and closure. + +```swift +drop.get("welcome") { request in + return "Hello" +} +``` + +The standard HTTP methods are available including `get`, `post`, `put`, `patch`, `delete`, and `options`. + +```swift +drop.post("form") { request in + return "Submitted with a POST request" +} +``` + +You can also use `any` to match all methods. + +## Alternate + +An alternate syntax that accepts a `Method` as the first parameter is also available. + +```swift +drop.add(.trace, "welcome") { request in + return "Hello" +} +``` + +This may be useful if you want to register routes dynamically or use a less common method. + +## Request + +Each route closure is given a single [Request](../http/request.md). This contains all of the data associated with the request that led to your route closure being called. + +## Response Representable + +A route closure can return in three ways: + +- `Response` +- `ResponseRepresentable` +- `throw` + +### Response + +A custom [Response](../http/response.md) can be returned. + +```swift +drop.get("vapor") { request in + return Response(redirect: "http://vapor.codes") +} +``` + +This is useful for creating special responses like redirects. It is also useful for cases where you want to add cookies or other items to the response. + +### Response Representable + +As you have seen in the previous examples, `String`s can be returned in route closures. This is because they conform to [ResponseRepresentable](../http/responserepresentable.md) + +A lot of types in Vapor conform to this protocol by default: +- String +- Int +- JSON +- Model + +```swift +drop.get("json") { request in + return try JSON(node: [ + "number": 123, + "text": "unicorns", + "bool": false + ]) +} +``` + +> If you are curious about what `node:` means, read more about [Node](../node/node.md) + +### Throwing + +If you are unable to return a response, you may `throw` any object that conforms to `Error`. Vapor comes with a default error enum `Abort`. + +```swift +drop.get("404") { request in + throw Abort.notFound +} +``` + +You can customize the message of these errors by using `Abort` + +```swift +drop.get("error") { request in + throw Abort.custom(status: .badRequest, message: "Sorry 😱") +} +``` + +These errors are caught by default in the `AbortMiddleware` where they are turned into a JSON response like the following. + +```json +{ + error: true, + message: "" +} +``` + +If you want to override this behavior, remove the `AbortMiddleware` from the `Droplet`'s middleware and add your own. diff --git a/routing/collection.md b/routing/collection.md new file mode 100644 index 00000000..e69de29b diff --git a/routing/group.md b/routing/group.md new file mode 100644 index 00000000..e69de29b diff --git a/routing/type-safe.md b/routing/type-safe.md new file mode 100644 index 00000000..e69de29b