What is ambiorix?
+Ambiorix is an unopinionated and minimalist web framework for R.
+It is inspired by express.js. In fact, the syntax is almost identical, only that it is R and not JavaScript.
+Ambiorix is a server-side or back-end framework. It is not comparable to client-side frameworks like React, Angular, Vue, etc. However, it can be used in combination with those frameworks to build full stack applications.
+“Unopinionated and Minimalist”… What does that mean?
+Ambiorix does not assume you’re going to build your API (or app) in any certain way or using a certain design pattern. You have absolute full control of how you handle requests to the server and how you respond.
+So, why should I use ambiorix?
+-
+
- Makes building web applications with R VERY easy +
- Used for both server rendered apps as well as API/Microservices +
- Full control of the request and response cycle +
- Great to use with your favorite client side framework (whether React, Angular, Vue etc.) +
What exciting features can I look forward to?
+Here are the features that make ambiorix well-suited to building large systems & applications:
+-
+
- Out of the box routing +
- Creating a robust API is quick and easy +
- Templating (html, markdown, etc.) +
- Websockets in case you need bidirectional communication +
What should I know first?
+The main prerequisites are:
+-
+
- having a good understanding of R fundamentals, and, +
- basic knowledge of HTTP status codes. +
You can pickup most of the concepts on the go.
+Package dependencies used in examples
+Each example has been bootstrapped using {renv} to ease reproducibility.
To install the dependencies for a specific example eg. 05_router:
-
+
Switch to its directory
+cd 05_router
+Add this to the
+.Renvironfile:RENV_CONFIG_SANDBOX_ENABLED = FALSE
+Fire up R and restore the dependencies:
+renv::restore()
+
"
+ )
+})
+```
+
+By making the `public/` folder static, any resource placed there can be
+accessed via the browser eg. http://localhost:3000/public/image.jpg
+
+### `/your-own-path`
+
+You can make static content accessible via your own custom path too.
+
+For example, let's use `/static` this time:
+
+```r
+app$static(path = "public", uri = "static")
+```
+
+Then in your code you'll use this:
+
+```r
+app$get("/", \(req, res) {
+ res$send(
+ "
"
+ )
+})
+```
+
+## Keep this in mind:
+
+- All static files are exposed and can be accessed via the browser. DO NOT put sensitive files there.
+- You can also use [htmltools](https://rstudio.github.io/htmltools/index.html) tags instead of writing html strings.
+
+## Basic routing
+
+Learn the ✨[basics of routing](../03_basic_routing/index.qmd)✨.
diff --git a/documentation/posts/03_basic_routing/delete-user.png b/documentation/posts/03_basic_routing/delete-user.png
new file mode 100644
index 0000000..4730d31
Binary files /dev/null and b/documentation/posts/03_basic_routing/delete-user.png differ
diff --git a/documentation/posts/03_basic_routing/get-home.png b/documentation/posts/03_basic_routing/get-home.png
new file mode 100644
index 0000000..5f99168
Binary files /dev/null and b/documentation/posts/03_basic_routing/get-home.png differ
diff --git a/documentation/posts/03_basic_routing/index.qmd b/documentation/posts/03_basic_routing/index.qmd
new file mode 100644
index 0000000..14ecd44
--- /dev/null
+++ b/documentation/posts/03_basic_routing/index.qmd
@@ -0,0 +1,110 @@
+---
+title: "03: basic routing"
+subtitle: "An intro to routes"
+author: "Kennedy Mwavu"
+date: "2024-07-10"
+categories: [03_basic_routing]
+---
+
+## Run app
+
+1. `cd` into the `03_basic_routing/` dir:
+
+ ```bash
+ cd 03_basic_routing/
+ ```
+
+1. Fire up R:
+
+ ```bash
+ R
+ ```
+
+1. Restore package dependencies:
+
+ ```r
+ renv::restore()
+ ```
+
+ Once done, exit R.
+1. `index.R` is the entry point. To start the app, run this on the terminal:
+
+ ```bash
+ Rscript index.R
+ ```
+
+## Explanation
+
+This app starts a server and listens on port 3000 for connections.
+
+It has two endpoints:
+
+- `/`
+- `/user`
+
+**Routing** refers to determining how an application responds to
+a client request to a particular endpoint, which is a URI (or
+path) and a specific HTTP request method (GET, POST, and so on).
+
+Each route can have one or more handler functions, which are
+executed when the route is matched.
+
+Route definition takes the following structure:
+
+```r
+app$METHOD(PATH, HANDLER)
+```
+
+- `app` is an instance of ambiorix.
+- `METHOD` is an [HTTP request method](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods), in lowercase.
+- `HANDLER` is the function executed when the route is matched.
+
+The following examples illustrate defining simple routes.
+
+Respond with `Hello World!` on the homepage:
+
+```r
+app$get("/", \(req, res) {
+ res$send("Hello World!")
+})
+```
+
+Respond to POST request on the root route (`/`), the application's home page:
+
+```r
+app$post("/", \(req, res) {
+ res$send("Got a POST request")
+})
+```
+
+Respond to a PUT request to the `/user` route:
+
+```r
+app$put("/user", \(req, res) {
+ res$send("Got a PUT request at /user")
+})
+```
+
+Respond to a DELETE request to the `/user` route:
+
+```r
+app$delete("/user", \(req, res) {
+ res$send("Got a DELETE request at /user")
+})
+```
+
+## Keep this in mind:
+
+- Browsers issue a GET request by default. This means that once you run this example and visit localhost 3000, you'll only be able to access the homepage (`/`).
+- The easiest way to see the responses from the other routes would be to either:
+ - Install [Postman](https://www.postman.com/) and make the requests from there (**Recommended**). The free tier is more than enough.
+ Here is how issuing the various requests above would look like:
+ 
+ 
+ 
+ 
+ - Open another R session and use [httr2](https://httr2.r-lib.org/index.html) to make requests to the endpoints.
+
+## A simple JSON API
+
+You're now ready to build ✨[a simple JSON API](../04_simple_json_api/index.qmd)✨.
\ No newline at end of file
diff --git a/documentation/posts/03_basic_routing/post-home.png b/documentation/posts/03_basic_routing/post-home.png
new file mode 100644
index 0000000..5cc1033
Binary files /dev/null and b/documentation/posts/03_basic_routing/post-home.png differ
diff --git a/documentation/posts/03_basic_routing/put-user.png b/documentation/posts/03_basic_routing/put-user.png
new file mode 100644
index 0000000..e24c476
Binary files /dev/null and b/documentation/posts/03_basic_routing/put-user.png differ
diff --git a/documentation/posts/04_simple_json_api/index.qmd b/documentation/posts/04_simple_json_api/index.qmd
new file mode 100644
index 0000000..a3ac2fb
--- /dev/null
+++ b/documentation/posts/04_simple_json_api/index.qmd
@@ -0,0 +1,250 @@
+---
+title: "04: simple json api"
+subtitle: "Build a simple API"
+author: "Kennedy Mwavu"
+date: "2024-07-10"
+categories: [04_simple_json_api]
+---
+
+## Run app
+
+1. `cd` into the `04_simple_json_api/` dir:
+
+ ```bash
+ cd 04_simple_json_api/
+ ```
+
+1. Fire up R:
+
+ ```bash
+ R
+ ```
+
+1. Restore package dependencies:
+
+ ```r
+ renv::restore()
+ ```
+
+ Once done, exit R.
+1. `server.R` is the entry point. To start the app, run this on the terminal:
+
+ ```bash
+ Rscript index.R
+ ```
+
+## Explanation
+
+This app starts a server and listens on port 3000 for connections.
+
+It has two endpoints:
+
+- `/api/members`
+- `/api/members/:id`
+
+Ideally, the backend works hand-in-hand with the database. But for the sake
+of simplicity, let's hardcode a list of members:
+
+```r
+members <- data.frame(
+ id = as.character(1:3),
+ name = c("John Doe", "Bob Williams", "Shannon Jackson"),
+ email = c("john@gmail.com", "bob@gmail.com", "shannon@gmail.com"),
+ status = c("active", "inactive", "active")
+)
+```
+
+You don't have to worry about converting `members` into JSON because the
+`res$json()` method does it for you.
+
+Create a GET request to get all members:
+
+```r
+app$get("/api/members", \(req, res) {
+ res$json(members)
+})
+```
+
+
+
+Create a GET request to get a single member by id:
+
+```r
+app$get("/api/members/:id", \(req, res) {
+ # get the supplied id:
+ member_id <- req$params$id
+
+ # filter member with that id:
+ found <- members |> dplyr::filter(id == member_id)
+
+ res$json(found)
+})
+```
+
+
+
+You can also dictate how the response changes if no member is found:
+
+```r
+# get a single member:
+app$get("/api/members/:id", \(req, res) {
+ # get the supplied id:
+ member_id <- req$params$id
+
+ # filter member with that id:
+ found <- members |> dplyr::filter(id == member_id)
+
+ # if a member with that id was found, return the member:
+ if (nrow(found) > 0) {
+ return(res$json(found))
+ }
+
+ # otherwise, change response status to 400 (Bad Request)
+ # and provide a message:
+ msg <- list(msg = sprintf("No member with the id of %s", member_id))
+ res$set_status(400L)$json(msg)
+})
+```
+
+
+
+A POST request to create a new member:
+
+```r
+app$post("/api/members", \(req, res) {
+ # parse form-data:
+ body <- parse_multipart(req)
+
+ # details of the new member:
+ new_member <- data.frame(
+ id = uuid::UUIDgenerate(),
+ name = body$name,
+ email = body$email,
+ status = body$status
+ )
+
+ # save new member:
+ members <<- dplyr::bind_rows(members, new_member)
+
+ # respond with a message and details of the newly created member:
+ response <- list(
+ msg = "Member created successfully!",
+ member = new_member
+ )
+
+ res$json(response)
+})
+```
+
+
+You can of course ensure all the details are sent (name, email & status) before
+creating the new member:
+
+```r
+app$post("/api/members", \(req, res) {
+ # parse form-data:
+ body <- parse_multipart(req)
+
+ name <- body$name
+ email <- body$email
+ status <- body$status
+
+ # require all member details:
+ if (is.null(name) || is.null(email) || is.null(status)) {
+ msg <- list(msg = "Please include a name, email & status")
+ return(res$set_status(400L)$json(msg))
+ }
+
+ # details of the new member:
+ new_member <- data.frame(
+ id = uuid::UUIDgenerate(),
+ name = name,
+ email = email,
+ status = status
+ )
+
+ # save new member:
+ members <<- dplyr::bind_rows(members, new_member)
+
+ # respond with a message and details of the newly created member:
+ response <- list(
+ msg = "Member created successfully!",
+ member = new_member
+ )
+
+ res$json(response)
+})
+```
+
+
+
+Create a PUT request to update a member:
+
+```r
+app$put("/api/members/:id", \(req, res) {
+ # get the supplied id:
+ member_id <- req$params$id
+
+ # filter member with that id:
+ found <- members |> dplyr::filter(id == member_id)
+
+ # if a member with that id is NOT found, change response status
+ # and provide a message:
+ if (nrow(found) == 0) {
+ msg <- list(msg = sprintf("No member with the id of %s", member_id))
+ return(res$set_status(400L)$json(msg))
+ }
+
+ # otherwise, proceed to update member:
+ body <- parse_multipart(req)
+
+ # only update provided fields:
+ found$name <- body$name %||% found$name
+ found$email <- body$email %||% found$email
+ found$status <- body$status %||% found$status
+
+ members[members$id == found$id, ] <- found
+
+ response <- list(
+ msg = "Member updated successfully",
+ member = found
+ )
+ res$json(response)
+})
+```
+
+
+
+Create a delete request to, well, delete a member:
+
+```r
+app$delete("/api/members/:id", \(req, res) {
+ # get the supplied id:
+ member_id <- req$params$id
+
+ # filter member with that id:
+ found <- members |> dplyr::filter(id == member_id)
+
+ # if a member with that id is NOT found, change response status
+ # and provide a message:
+ if (nrow(found) == 0) {
+ msg <- list(msg = sprintf("No member with the id of %s", member_id))
+ return(res$set_status(400L)$json(msg))
+ }
+
+ # otherwise, proceed to delete member:
+ members <<- members |> dplyr::filter(id != member_id)
+
+ response <- list(
+ msg = "Member deleted successfully",
+ members = members
+ )
+ res$json(response)
+})
+```
+
+
+
+## Router
+
+Things are getting out of hand in `server.R`. Take a look at ✨[routers](../05_router/index.qmd)✨.
diff --git a/documentation/posts/04_simple_json_api/screenshots/delete-api-member-id.png b/documentation/posts/04_simple_json_api/screenshots/delete-api-member-id.png
new file mode 100644
index 0000000..3c422f2
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/delete-api-member-id.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/get-api-member-id-not-found.png b/documentation/posts/04_simple_json_api/screenshots/get-api-member-id-not-found.png
new file mode 100644
index 0000000..81bbb50
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/get-api-member-id-not-found.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/get-api-member-id.png b/documentation/posts/04_simple_json_api/screenshots/get-api-member-id.png
new file mode 100644
index 0000000..3effb74
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/get-api-member-id.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/get-api-members.png b/documentation/posts/04_simple_json_api/screenshots/get-api-members.png
new file mode 100644
index 0000000..a2e5b3e
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/get-api-members.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/post-api-members-required-fields.png b/documentation/posts/04_simple_json_api/screenshots/post-api-members-required-fields.png
new file mode 100644
index 0000000..ca7c21e
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/post-api-members-required-fields.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/post-api-members.png b/documentation/posts/04_simple_json_api/screenshots/post-api-members.png
new file mode 100644
index 0000000..c1004d6
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/post-api-members.png differ
diff --git a/documentation/posts/04_simple_json_api/screenshots/put-api-member-id.png b/documentation/posts/04_simple_json_api/screenshots/put-api-member-id.png
new file mode 100644
index 0000000..1409820
Binary files /dev/null and b/documentation/posts/04_simple_json_api/screenshots/put-api-member-id.png differ
diff --git a/documentation/posts/05_router/index.qmd b/documentation/posts/05_router/index.qmd
new file mode 100644
index 0000000..082f56c
--- /dev/null
+++ b/documentation/posts/05_router/index.qmd
@@ -0,0 +1,138 @@
+---
+title: "05: router"
+subtitle: "What's a router?"
+author: "Kennedy Mwavu"
+date: "2024-07-10"
+categories: [05_router]
+---
+
+## Run app
+
+1. `cd` into the `05_router/` dir:
+
+ ```bash
+ cd 05_router/
+ ```
+
+ - There are 2 directories there: `box/` & `r_pkg_structure/`.
+ - `cd` into any of them, say, `r_pkg_structure/`:
+
+ ```bash
+ cd r_pkg_structure/
+ ```
+
+1. Fire up R:
+
+ ```bash
+ R
+ ```
+
+1. Restore package dependencies:
+
+ ```r
+ renv::restore()
+ ```
+
+ Once done, exit R.
+1. `server.R` is the entry point. To start the app, run this on the terminal:
+
+ ```bash
+ Rscript index.R
+ ```
+
+## Explanation
+
+This app starts a server and listens on port 3000 for connections.
+
+It has two endpoints:
+
+- `/api/members`
+- `/api/members/:id`
+
+**Routing** refers to how an application's endpoints (URIs) respond to client requests.
+
+For an introduction to routing, see [03_basic_routing](../03_basic_routing/index.qmd).
+
+If you look at [04_simple_json_api](../04_simple_json_api/index.qmd) you'll notice that the routes we created all belong to `/api/members` and we kept repeating that base/root route.
+
+Wouldn't it be nice to only have to use `/` and `/:id` and have ambiorix prepend the `/api/members` automatically?
+
+That would give you a better app structure making it manageable.
+
+## Enter `ambiorix::Router()`.
+
+Use the `ambiorix::Router` class to create modular, mountable router handlers.
+
+A `Router` instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app".
+
+Using the example [04_simple_json_api](../04_simple_json_api/index.qmd), this is how we would transform it:
+
+```r
+# members.R
+members_router <- \() {
+ router <- Router$new("/members")
+
+ # get all members:
+ router$get("/", \(req, res) {
+ # ...
+ })
+
+ # get a single member:
+ router$get("/:id", \(req, res) {
+ # ...
+ })
+
+ # create a new member:
+ router$post("/", \(req, res)) {
+ # ...
+ }
+
+ # update member:
+ router$put("/:id", \(req, res) {
+ # ...
+ })
+
+ # delete member:
+ router$delete("/:id", \(req, res) {
+ # ...
+ })
+
+ router
+}
+```
+
+The `server.R` file would now be:
+
+```r
+library(ambiorix)
+
+#