Ring Requests

Here's an example GET request from guest123 to http://localhost/index.html:

{:server-port 80,
 :server-name "localhost",
 :remote-addr "guest123",
 :uri "/index.html",
 :query-string nil,
 :scheme :http,
 :request-method :get,
 :headers {"host" "localhost"}}

We'll be talking a lot about Ring requests in upcoming sections, but for now the important thing is to get a general idea of what they look like. If you've written web services before, you should see what's going on in the example above. Remember, since this is a normal Clojure map, we can access these fields using the key as a function, such as (:request-method request) would return :get. If you want to get the value of the host header, you can use (get-in request [:headers "host"]), and so on.

Not all requests are that simple. Here's a POST request from localhost to http://localhost/links with a body:

{:remote-addr "localhost",
 :headers
 {"host" "localhost",
  "content-type" "application/x-www-form-urlencoded",
  "content-length" "28"},
 :server-port 80,
 :content-length 28,
 :content-type "application/x-www-form-urlencoded",
 :uri "/links",
 :server-name "localhost",
 :query-string nil,
 :body #object[java.io.ByteArrayInputStream]...,
 :scheme :http,
 :request-method :post}

Most of this example is fairly clear: You have some extra headers relating to the body (as expected), so the :request-method now says :post, the :uri key gives the path to the links endpoint, etc. What may be a bit surprising is that the :body key now points to a java.io.ByteArrayInputStream. This class has some gotchas covered later, in addition to a string and a native data structure.

Ring Responses

Ideally, every request should be met with a response, and Ring represents those with maps as well. Here's a simple Hello World response map:

{:status 200,
 :headers {"Content-Type" "text/html; charset=utf-8"},
           :body "Hello World"}

As you can see, HTTP responses are much simpler than requests—all you have to worry about are the status code, the headers, and the body. For some responses, the body is expected to be blank. Take a typical 302 redirect, such as:

{:status 302,
 :headers {"Location" "http://example.com"},
 :body ""}

Here, the important content is included under the "Location" header, rather than the body. Note that the body is still included, even though it's just the empty string. This is a practice that you should observe in your own responses, and Ring's built-in response helpers will add it for you where appropriate.

Now that you've seen both request and response maps, you can begin to think of your web service as a series of functions from the former to the latter. If you remember nothing else, remember that a function that takes a request and returns a response is called a handler.

Response Helpers

A 404 Not Found response from the example project will look something like this:

{:status 404,
 :headers
 {"Content-Type" "text/html; charset=utf-8",
  "Set-Cookie"
  ("ring-session=855650aa-6209-48af-944f-177cac7fad56;Path=/;HttpOnly"),
   "X-XSS-Protection" "1; mode=block",
   "X-Frame-Options" "SAMEORIGIN",
   "X-Content-Type-Options" "nosniff"},
  :body "Not Found"}

Although it's possible to write a response map by hand, it's usually not done that way. Instead, the process is typically broken down into two main phases:

1. Create the response using helpers from the ring.util.response namespace.
2. Apply middleware to outgoing responses to add common headers.

In the case of the compojure template, nearly all the preceding map is created by a combination of compojure.route/not-found and ring.middleware.defaults/wrap-defaults, both of which we'll cover later in this chapter.

For now, though, let's look at how to use the ring.util.response helpers to create a similar map:

(require '[ring.util.response :as ring-response])
(def my404
  (-> (ring-response/response "Not found")
    ;; returns a basic response map with "Not found" in the body
    (ring-response/status 404)
    ;; updates the status of the response to 404
    (ring-response/content-type "text/html")
    ;; adds the Content-Type header to the response
    (ring-response/charset "utf-8")
    ;; extends the Content-Type header to include the character set
    ))

With the notable exception of ring.util.response/response (which takes only a body), most of the helper functions take a response map as their first argument. What this means in practice is that you'll almost always use them with the -> (thread-first) macro, so you can read the whole expression as a series of updates to the immutable response map.

After evaluating the above forms, my404 looks like this:

{:status 404,
 :headers {"Content-Type" "text/html; charset=utf-8"},
 :body "Not found"}

It's still missing a lot of the headers from the template's 404 response, but it's the job of the middleware to handle those.

You should take a moment to browse the ring.util.response namespace once or twice to get an idea of what you can do with Ring responses without having to reinvent the wheel, so to speak. You'll find that most of the functions are short and accomplish one task reliably, which makes them great examples for your own helpers.

Testing Ring Handlers

One of the great things about Ring is how easy it is to test. Recall how one of the added benefits of the compojure template is that it automatically adds a dependency on ring-mock. This section covers how ring-mock is used to test ring handlers without having to start a live HTTP server.

First of all, run lein test in the project directory (if you haven't already) to verify that they do pass. Once you're satisfied, look at how the tests actually work:

(ns chapter3.handler-test
  (:require [clojure.test :refer :all]
            [ring.mock.request :as mock]
            [chapter3.handler :refer :all]))
(deftest test-app
  (testing "main route"
           (let [response (app (mock/request :get "/"))]
             (is (= (:status response) 200))
             (is (= (:body response) "Hello World"))))
  (testing "not-found route"
           (let [response (app (mock/request :get "/invalid"))]
             (is (= (:status response) 404)))))

Notice that app is being called like a function (because handlers are functions), but it's being passed the mock/request thing. Let's see what happens if you evaluate (mock/request :get "/") in a REPL:

{:server-port 80,
 :server-name "localhost",
 :remote-addr "localhost",
 :uri "/",
 :query-string nil,
 :scheme :http,
 :request-method :get,
 :headers {"host" "localhost"}}

It's a Ring request map! Only this one has a lot of the boring stuff filled in for us, which makes the tests much easier to read. Let's continue by evaluating the whole expression (app (mock/request :get "/")):

{:status 200,
 :headers {"Content-Type" "text/html; charset=utf-8"},
           :body "Hello World"}

If you guessed that this is a Ring response map, you're absolutely correct. Once again, you can clearly see that Ring handlers are ordinary Clojure functions that take a (request) map as a parameter and return a (response) map. What's interesting is that these tests are avoiding actual HTTP transport by just calling the handlers directly—there's no network traffic involved.

The ring.mock.request/request function can just as easily generate a :post request, which will be very helpful later when we talk about ByteArrayInputStreams. Try it out with (mock/request :post "/foo" "Hello, this request has a body"):

{:remote-addr "localhost",
 :headers {"host" "localhost", "content-length" "30"},
 :server-port 80,
 :content-length 30,
 :uri "/foo",
 :server-name "localhost",
 :query-string nil,
 :body
 #object[java.io.ByteArrayInputStream 0x6e9da8f2 "java.io.ByteArrayInputStream..."],
 :scheme :http,
 :request-method :post} 

Another thing that's worth remarking on is that there's only one handler for our entire (small) application: app. That's a result of Compojure doing its job, which is to compose handlers for various routes into a single handler that can answer any request it gets. This is covered more in the "Routing" section.

The ring-mock library only includes a few functions, most of which fine-tune the requests generated by ring.mock.request/request by updating headers, adding query parameters, and more. If you find yourself needing to create more sophisticated requests in your tests, have a quick look at the ring.mock.request namespace first to see if it has what you need.

Ring Middleware

Recall that handlers are functions that turn a request into a response, and they are the fundamental concept in Ring. The term middleware refers to a function that takes a handler and returns a handler. Because middleware has the same type for its parameter and return value, you can stack them indefinitely—middleware upon middleware upon middleware, until you get down to a basic handler.

(defn wrap-500-catchall
  "Wrap the given handler in a try/catch expression, returning a 500 response if
  any exceptions are caught."
  [handler] ;; we want to take a handler as a parameter
  (fn [request] ;; we're also returning a handler
    (try (handler request)
      ;; middleware almost always calls the handler that's passed in
      (catch Exception e
        (-> (ring-response/response (.getMessage e))
          ;; place the exception's message in the body
          (ring-response/status 500)
          ;; set the status code to 500
          (ring-response/content-type "text/plain")
          ;; there's no HTML here, so we'll use text/plain
          (ring-response/charset "utf-8")
          ;; and update the character set
          )))))

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (route/not-found "Not Found"))

(def app
  (wrap-500-catchall (wrap-defaults app-routes site-defaults)))

(deftest catchall-test
  (testing "when a handler throws an exception"
    (let [response (app (mock/request :get "/trouble"))]
      (testing "the status code is 500"
        (is (= 500 (:status response))))
      (testing "and the body only contains the exception message"
        (is (= "Divide by zero" (:body response)))))))

user=> (require '[ring.mock.request :as mock])
nil
user=> (def request-with-body (mock/request :post "/" "This is the request body"))
#'user/request-with-body
user=> (:body request-with-body)
#object[java.io.ByteArrayInputStream 0x71e6fe51 "java.io.ByteArrayInputStream@..."]

user=> (slurp (:body request-with-body))
"This is the request body"

user=> (slurp (:body request-with-body))
""

(defn wrap-slurp-body
  [handler]
  (fn [request]
    (if (instance? java.io.InputStream (:body request))
      (let [prepared-request (update request :body slurp)]
        (handler prepared-request))
      (handler request))))

(defn body-echo-handler
  [request]
  (if-let [body (:body request)] ;; remember, not all requests have bodies!
    (-> (ring-response/response body)
      (ring-response/content-type "text/plain")
      (ring-response/charset "utf-8"))
    ;; if there's no body, let's call this a 400 (Bad request)
    (-> (ring-response/response "You must submit a body with your request!")
      (ring-response/status 400))))

(def body-echo-app
(-> body-echo-handler
  wrap-500-catchall
  wrap-slurp-body))

(deftest slurp-body-test
  (testing "when a handler requires a request body"
    (testing "and a body is provided"
      (let [response (body-echo-app (mock/request :post "/" "Echo!"))]
        (testing "the status code is 200"
          (is (= 200 (:status response)))
          (testing "with the request body in the response body"
            (is (= "Echo!" (:body response)))))))
    (testing "and a body is not provided"
      (let [response (body-echo-app (mock/request :get "/"))]
        (testing "the status code is 400"
          (is (= 400 (:status response))))))))

(def app
  (-> app-routes
    (wrap-defaults api-defaults)
    wrap-slurp-body
    wrap-500-catchall))

(def app
  (-> app-routes
    wrap-500-catchall
    (wrap-defaults api-defaults)
    wrap-slurp-body))

Composing Routes

The chapter3.handler namespace already has three Compojure routes defined under app-routes:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0))
  (route/not-found "Not Found"))

The defroutes macro is purely a convenience around def (you've seen) and routes ( will be covered in depth soon). Just to prove there's no other magic involved, let's revise this bit of code to eliminate the use of defroutes:

(def app-routes
  (routes
   (GET "/" [] "Hello World")
   (GET "/trouble" [] (/ 1 0))
   (route/not-found "Not Found")))

Now that the structure is easier to see, let's talk about what's going on here. Although it might not look much like it right now, remember that app-routes is a handler. That is, app-routes takes a Ring request map and returns a response map.

That fact alone gives you a good idea of what routes does: It takes some number of Compojure routes and turns them into a single handler. But what are the routes individually? Have a guess, then open up a REPL in the project directory:

user=> (require '[compojure.core :refer :all])
nil
user=> (def get-foo (GET "/foo" [] "Hello from foo"))
#'user/get-foo
user=> (require '[ring.mock.request :as mock])
nil
user=> (get-foo (mock/request :get "/foo"))
{:status 200,
 :headers {"Content-Type" "text/html; charset=utf-8"},
 :body "Hello from foo"}

As you can see, GET (and indeed, the PUT/POST/DELETE/etc.) returns a handler. In this case, you'll test it out with a request that the handler was ready for—a simple GET request to /foo. Let's jump back to the REPL and see what happens if the route doesn't match:

user=> (get-foo (mock/request :get "/"))
nil

Well, nil isn't a valid Ring response, so it would be a really bad idea to use this handler directly. Let's look again at app-routes:

(def app-routes
  (routes
   (GET "/" [] "Hello World")
   (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
   (route/not-found "Not Found")))

Now that you know that each route is a handler that can return nil, you can fully deduce the purpose of the routes function: to combine multiple handlers, sending the request to each one until a valid response (not nil) is returned.

This is the first function that can turn two or more handlers into one, and it's about time! You don't want to write one huge handler all at once to represent the application; it's much more reasonable to split it up and handle one route at a time.

Writing Routes

Here again are some simple Compojure routes:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (route/not-found "Not Found"))

There's definitely a common structure here:

• HTTP verb, like GET, PUT, POST, DELETE
• A path
• A parameter vector
• The body of the response

Most of the time, Compojure routes resemble Clojure functions. Instead of defn, each route is introduced with the HTTP verb it responds to. Standing in for the function name is the path, which can contain abstract segments such as :id. Like an ordinary function, a route must have a (possibly empty) parameter vector, which supports the standard destructuring forms. Finally, you can define the result of matching the route by providing an expression to evaluate.

The routes above are extremely simple, which is good when trying not to dive too deep into routing, but now it's time to jump in with both feet. Let's bring the echo handler into Compojure:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0))
  (POST "/echo" [:as request] (body-echo-handler request))
  (route/not-found "Not Found"))

This finally gives you something more interesting to look at in the parameter vector, so let's focus on that first. You may recognize :as, which is part of Clojure's standard destructuring syntax. Normally, :as x would take all of the parameters and wrap them up in a collection called x. In Compojure specifically, :as is a nice shortcut to get the entire Ring request as a parameter so that it can be passed off to a handler. The request can have any name, but in this case it's hard to imagine a reason not to call it request. Once you have the request in scope, call the old body-echo-handler directly.

Let's revisit the tests for app-routes and add a couple for the newly integrated echo endpoint:

(deftest test-app
  (testing "main route"
    (let [response (app (mock/request :get "/"))]
      (is (= (:status response) 200))
      (is (= (:body response) "Hello World"))))
  (testing "echo route"
    (let [response (app (mock/request :post "/echo" "Echo!"))]
      (is (= 200 (:status response)))
      (is (= "Echo!" (:body response))))
    (let [response (app (mock/request :post "/echo"))]
      (is (= 400 (:status response)))))
  (testing "not-found route"
    (let [response (app (mock/request :get "/invalid"))]
      (is (= (:status response) 404)))))

This works for POST, but this handler is used to accepting any request that contains a body. You can work your way back up to the old functionality like this:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0))
  (POST "/echo" [:as request] (body-echo-handler request))
  (PUT "/echo" [:as request] (body-echo-handler request))
  (DELETE "/echo" [:as request] (body-echo-handler request))
  (route/not-found "Not Found"))

Or maybe this doesn't work. This amount of code duplication is unforgivable, even in this small example project. Let's take advantage of another routing function that Compojure provides:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (ANY "/echo" [:as request] (body-echo-handler request))
  (route/not-found "Not Found"))

Now you can match any HTTP request to the /echo path. Let's verify that by adding a few more requests to the tests for the echo route:

(deftest test-app
  (testing "main route"
    (let [response (app (mock/request :get "/"))]
      (is (= (:status response) 200))
      (is (= (:body response) "Hello World"))))
  (testing "echo route"
    (let [response (app (mock/request :post "/echo" "Echo!"))]
      (is (= 200 (:status response)))
      (is (= "Echo!" (:body response))))
    (let [response (app (mock/request :put "/echo" "Hello!"))]
      (is (= 200 (:status response)))
      (is (= "Hello!" (:body response))))
    (let [response (app (mock/request :patch "/echo" "Goodbye!"))]
      (is (= 200 (:status response)))
      (is (= "Goodbye!" (:body response))))
    (let [response (app (mock/request :post "/echo"))]
      (is (= 400 (:status response)))))
  (testing "not-found route"
    (let [response (app (mock/request :get "/invalid"))]
      (is (= (:status response) 404)))))

There's more to do here to clean up the echo handler. Although convenient, it's usually unnecessary to pass along the entire request to a Compojure route handler. In this case, all the echo handler actually needs is the body, which may be nil. Leave echo-body-handler in place, but write a new function that doesn't rely on any extraneous data:

(defn echo ;; based on echo-body-handler
  [body]
  (if (not-empty body) ;; excludes nil and the empty string
    (-> (ring-response/response body)
      (ring-response/content-type "text/plain")
      (ring-response/charset "utf-8"))
    ;; if there's no body, let's call this a 400 Malformed
    (-> (ring-response/response "You must submit a body with your request!")
      (ring-response/status 400))))

Notice how the function is renamed to echo. Since it no longer takes a full request map, it would be misleading to give it a name with handler in it. Also, since it only takes the body as a parameter, it doesn't make sense to also put body in the name. So that leaves you with echo. Unfortunately, the tests are also failing now, so you need to update app-routes to only pass the body along to this function:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (ANY "/echo" [:as {body :body}] (echo body))
  (route/not-found "Not Found"))

Notice how the request was replaced with {body :body}. The latter is also standard destructuring syntax, roughly translating to "take whatever's in the :body key and bind it to body." Leave the :as there to make sure that you're destructuring the request map; otherwise you'll get an error about an unexpected binding form. Go ahead and run the tests again to make sure everything's back in working order with the newly refactored handler.

Compojure Responses

You may have noticed that Compojure doesn't seem to mind if a string is returned instead of a proper ring response map. This is not practical most of the time because you need to add a bit more with the request. Still, it's worth taking note of exactly how Compojure is able to turn that string into a Ring response, since you can extend that behavior to other types that might be more useful.

Compojure uses the compojure.response/Renderable protocol for this purpose. The protocol defines a single method, render, which returns a proper Ring response. You can take a look at the compojure.response namespace to see how this method is defined for nil, strings, maps, etc.

Path Variables

At the beginning of this section, a route is mentioned with an abstract segment: /links/{ID}, where {ID} is an extra parameter that the handler can use. Compojure also makes this quite easy with a little bit of magic:

(defroutes app-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0))
  (GET "/links/:id" [id] (str "The id is: " id))
  (ANY "/echo" [:as {body :body}] (echo body))
  (route/not-found "Not Found"))

Here you have a new route, /links/:id, with just [id] for the parameter vector. When Compojure matches a route, any segments that start with a colon are treated as abstract path segments and added to the request map. You can access them through the request yourself, but Compojure also adds a more convenient way—providing the name of the segment in the parameter vector. That means that you can't use, say, [link-id] for the parameter name; it wouldn't have matched.

Let's write some tests to verify that the /links/:id endpoint actually works:

(deftest links-test
  (testing "the links/:id endpoint"
    (testing "when an id is provided"
      (let [response (app (mock/request :get "/links/foo123"))]
        (testing "returns a 200"
          (is (= 200 (:status response)))
          (testing "with the id in the body"
            (is (re-find #"foo123" (:body response)))))))
    (testing "when the id is omitted"
      (let [response (app (mock/request :get "/links"))]
        (testing "returns a 404"
          (is (= 404 (:status response))))))
    (testing "when the path is too long"
      (let [response (app (mock/request :get "/links/foo123/extra-segment"))]
        (testing "returns a 404"
          (is (= 404 (:status response))))))))

As the tests show, the route will only match if there is exactly one segment for :id—anything else will result in a 404.

Routes and Middleware

Using middleware to your advantage is always a good idea, but you don't always want to apply the same middleware to every route. For example, you don't actually need to apply the wrap-slurp-body middleware to all of the routes just because the /echo endpoint relies on it. Instead, you can group routes and apply middleware in multiple stages. First, split off the /echo route from the rest of app-routes:

(def body-routes
  (-> (routes
       (ANY "/echo" [:as {body :body}] (echo body)))
    (wrap-routes wrap-slurp-body)))
(defroutes non-body-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (GET "/links/:id" [id] (str "The id is: " id))
  (route/not-found "Not Found"))

Note that we're wrapping body-routes directly, rather than at a later stage. This works well conceptually, since any route that gets grouped under body-routes is going to need this middleware and other routes probably won't. This pattern isn't possible with the defroutes macro because there's no way to sneak in the middleware between def and routes in that case.

The other very important note here is that even though you can call wrap-slurp-body on the route, you'll instead pass it as an argument to wrap-routes. The rationale for this has to do with the way that Compojure combines handlers. When you pass multiple handlers to routes, they each get called with the request map until one of them returns a response. If one of those handlers somehow mutates the request map (which wrap-slurp-body does, because it consumes the original body), then subsequent handlers will see the mutated version.

The wrap-routes function is an essential workaround for this problem. It ensures that the given middleware is only applied when the route actually matches, meaning that it will only be called once per request. You should use wrap-routes whenever you're applying middleware with the routes function.

Moving on, instead of wrapping only app-routes in the remaining middleware, you can combine body-routes with app-routes. First, combine body-routes and app-routes into a single handler with the routes function:

(def app-routes
  (routes body-routes non-body-routes))

Next, remove wrap-slurp-body from the app, since it has already been applied to the routes that require it:

(def app
  (-> app-routes
    wrap-500-catchall
    (wrap-defaults api-defaults)))

It's very rare that all of your routes will need exactly the same middleware in exactly the same order, so always think about that when grouping routes together. You can always wrap handlers in middleware and you can always group handlers with routes, so you'll often see a sort of group-wrap-group-wrap-group-wrap pattern that slowly combines handlers into a single application.

Accepting JSON Data

Now that we're equipped to deal with JSON, let's write some middleware to handle parsing a JSON-encoded body, thus returning a 400 response if it's malformed:

(defn wrap-json
  [handler]
  (fn [request]
    (if-let [prepd-request (try (update request :body json/decode)
                             (catch com.fasterxml.jackson.core.JsonParseException e
                               nil))]
      (handler prepd-request)
      ;; we'll only get here if there's a parse error
      (-> (ring-response/response "Sorry, that's not JSON.")
        (ring-response/status 400)))))

One thing to note is that this middleware assumes that the body is going to be a string, which means it'll have to be applied before wrap-slurp-body (remember, applied first means called second). Let's write a handler that turns a JSON-encoded body into a Clojure map:

(defn handle-clojurefy
  [request]
  (-> (:body request) ;; extract the body of the request
    str ;; turn it into a string
    ring-response/response ;; wrap it in a response map
    (ring-response/content-type "application/edn"))) ;; set the Content-Type

Note the proper Ring handler is written here, rather than taking any of the shortcuts that Compojure opens up. This is usually the right thing to do—full Ring handlers are easier to test independently and they tend to be more explicit. In this case, returning a response map makes it possible to set the Content-Type to application/edn. If you're not familiar with EDN (Extensible Data Notation), it's essentially Clojure's built-in object serialization standard, and it can be a convenient way to pass data between Clojure services over HTTP.

Let's add the /clojurefy endpoint to body-routes, since it does require a body. You will wrap it with the wrap-json middleware right in the route definition:

(def body-routes
  (-> (routes
       (ANY "/echo" [:as {body :body}] (echo body))
       (POST "/clojurefy" [] (wrap-json handle-clojurefy)))
    wrap-slurp-body))

Remember the compojure.response/Renderable protocol? Well, it turns out that you can use it to skip the whole [:as request] bit. When you use a full-fledged Ring handler for the body of a route, Compojure assumes it's a handler and automatically passes it the request map. It looks a little strange, but it works, and the alternative looks even stranger:

(POST "/clojurefy" [:as request] ((wrap-json handle-clojurefy) request)) ;; weird!

Also note that wrap-json is placed where it can only see requests that have matched the /clojurefy route. This way it won't affect the /echo endpoint, which really doesn't care if the request contains valid JSON.

Finally, let's write some tests to see if this is successful:

(deftest json-test
  (testing "the /clojurefy endpoint"
    (testing "when provided with some valid JSON"
      (let [example-map {"hello" "json"}
            example-json (json/encode example-map)
            response (app (-> (mock/request :post "/clojurefy" example-json)
                            ;; note, we must set the content type of the request
                            (mock/content-type "application/json")))]
        (testing "returns a 200"
          (is (= 200 (:status response)))
          (testing "with a Clojure map in the body"
            (is (= (str example-map) (:body response)))))))
    (testing "when provided with invalid JSON"
      (let [response (app (-> (mock/request :post "/clojurefy" ";!:")
                            (mock/content-type "application/json")))]
        (testing "returns a 400"
          (is (= 400 (:status response))))))))

The tests pass, so all is good! Let's move on to returning JSON responses.

Returning JSON Data

Returning JSON is a bit easier than accepting it. You don't have to worry about problems with parsing; you just need to set the content type and encode the body. Here's a simple middleware function that should take care of this:

(defn wrap-json-response
  [handler]
  (fn [request]
    (-> (handler request) ;; call the handler first
      (update :body json/encode) ;; then encode the body
      (ring-response/content-type "application/json")))) ;; and set Content-Type

Most of the middleware written for this book so far alters incoming requests, so this is a little bit different. Instead of calling the handler last, you call it first. For the rest of the thread-first form let's work with the response map. Thread the response through update to encode the body, then use ring.util.response/content-type to apply the correct Content-Type header.

Now, let's write a handler that returns a JSON object with some basic information about the system it's running on:

(def handle-info
  (wrap-json-response
   (fn [_] ;; we don't actually need the request
     (-> {"Java Version" (System/getProperty "java.version")
          "OS Name" (System/getProperty "os.name")
          "OS Version" (System/getProperty "os.version")}
       ring-response/response))))

This is yet another way to wrap a handler. Since there is only one handler that returns JSON, there's no real problem with wrapping it this closely. If you had a few more routes like this, you'd want to compose them and then wrap the combined handler.

This handler uses the System/getProperty method to fetch some details about the host that the service is running on. You may not want to expose this information generally, but it's a useful thing to know about and a perfectly good source of structured data to encode.

Now let's add a route for the /info endpoint:

(defroutes non-body-routes
  (GET "/" [] "Hello World")
  (GET "/trouble" [] (/ 1 0)) ;; this won't end well!
  (GET "/links/:id" [id] (str "The id is: " id))
  (GET "/info" [] handle-info)
  (route/not-found "Not Found"))

In this case, it will be more interesting to run lein ring server and check out http://localhost:3000/info, but let's write some tests anyway:

(deftest json-response-test
  (testing "the /info endpoint"
    (let [response (app (mock/request :get "/info"))]
      (testing "returns a 200"
        (is (= 200 (:status response))))
      (testing "with a valid JSON body"
        (let [info (json/decode (:body response))]
          (testing "containing the expected keys"
            (is (= #{"Java Version" "OS Name" "OS Version"}
                   (set (keys info))))))))))

One thing to note here is that the keys function makes no guarantees about the order that the keys are in, so you'll use a set comparison to make sure that you don't need any such guarantees. As long as the map has exactly the keys "Java Version," "OS Name," and "OS Version" in any order, the test will pass.

Using ring-json

Writing your own JSON middleware is great practice, but the fact is that this has already been done for you. The ring-clojure organization maintains a very helpful library called ring-json (https://github.com/ring-clojure/ring-json). This library already provides a default 400 response, as well as middleware for JSON requests and JSON responses.

So, in the interest of not reinventing the wheel, let's refactor the code to use the ring-json library. First, add it as a dependency to project.clj:

:dependencies [[org.clojure/clojure "1.7.0"]
               [compojure "1.4.0"]
               [ring/ring-defaults "0.1.5"]
               [ring/ring-json "0.4.0"] ;; add this
               [cheshire "5.5.0"]]

Then require ring.middleware.json in handler.clj:

(ns chapter3.handler
  (:require [compojure.core :refer :all]
            [ring.middleware.json :as ring-json] ;; add this
            [ring.util.response :as ring-response]
            [ring.util.request :as ring-request]
            [compojure.route :as route]
            [cheshire.core :as json]
            [ring.middleware.defaults :refer [wrap-defaults api-defaults]]))

We have a slightly different middleware situation right now because ring-json's version of wrap-json-body stringifies the request body for us; making wrap-slurp-body obsolete for JSON routes. Let's go ahead and move the /clojurefy endpoint out of body-routes and into its own json-routes var while you replace wrap-json with ring-json/wrap-json-body:

(def json-routes
  (routes
   (POST "/clojurefy" [] (ring-json/wrap-json-body handle-clojurefy))))
(def body-routes
  (-> (routes
       (ANY "/echo" [:as {body :body}] (echo body)))
    (wrap-routes wrap-slurp-body)))

You'll also need to update app-routes to include json-routes:

(def app-routes
  (routes json-routes body-routes non-body-routes))

Next, you'll replace wrap-json-response middleware with ring-json/wrap-json-response:

(def handle-info
  (ring-json/wrap-json-response
   (fn [_] ;; we don't actually need the request
     (-> {"Java Version" (System/getProperty "java.version")
          "OS Name" (System/getProperty "os.name")
          "OS Version" (System/getProperty "os.version")}
       ring-response/response))))

Once those changes are made, you can delete both of the hand-crafted JSON middleware functions and re-run the tests. The functionality hasn't changed in any particularly significant way, so they all pass.

JSON endpoints need not be especially daunting, provided you're smart about the abstractions that are available. Use middleware for parsing and encoding, but be very careful about applying it only where necessary and always think twice about the order in which middleware is applied. Avoid writing your own middleware if there's already a good open source solution for it. Although this section focused on JSON, you can easily apply the exact same principles to any other form of serialization.

Middleware

You're undoubtedly going to need some middleware for this project, so let's create a new file at src/ch3shortener/middleware.clj with these contents:

(ns ch3shortener.middleware)

It's not much to look at for now, but it's a start. You should also be prepared to write middleware tests, so create another file attest/ch3shortener/middleware_test.clj with these contents:

(ns ch3shortener.middleware-test
  (:require [ch3shortener.middleware :refer :all]
            [clojure.test :refer :all]))

Even though you haven't done it yet, you can test middleware independently. Doing so helps you figure out whether a given bug is caused by the middleware itself, middleware ordering, or the handler. You'll have a look at that strategy later on when there is some middleware to test.

Routes

The routes namespace should look like a high-level overview of the endpoints your service makes available. It's important to have a good place to start when you're looking to add or update an existing route. Let's create the routes' namespace at src/ch3shortener/routes.clj and copy over the routes themselves from handler.clj:

(ns ch3shortener.routes
  (:require [ch3shortener.handler :as handler]
            [ch3shortener.middleware :as mw]))
(defroutes app-routes
  (GET "/" [] "Hello World")
  (route/not-found "Not Found"))

You won't have independent tests for routes, so this is all you need for now.

Application

The application namespace is about to unseat ch3shortener.handler as the main point of entry for our service. Create the file src/ch3shortener/application.clj with the following contents:

(ns ch3shortener.application
  (:require [ring.middleware.defaults :refer [wrap-defaults site-defaults]]
            [ch3shortener.routes :as routes]))
(def app
  (wrap-defaults routes/app-routes site-defaults))

This should look familiar, since it's basically just the rest of the ch3shortener.handler namespace with the added dependency on ch3shortener.routes. Similarly, let's create test/ch3shortener/application_test.clj and move the existing handler tests there:

(ns ch3shortener.application-test
  (:require [ch3shortener.application :refer :all]
            [clojure.test :refer :all]
            [ring.mock.request :as mock]))
(deftest test-app
  (testing "main route"
    (let [response (app (mock/request :get "/"))]
      (is (= (:status response) 200))
      (is (= (:body response) "Hello World"))))
  (testing "not-found route"
    (let [response (app (mock/request :get "/invalid"))]
      (is (= (:status response) 404)))))

The last thing you need to do to make ch3shortener.application/app the main handler for your service is to update the :ring section in project.clj:

  :ring {:handler ch3shortener.application/app}

This configuration option tells Ring which handler to use when starting a server with lein ring server. Once you update the setting, try that command out and verify that everything still works. You should see exactly the same behavior as before, only with better namespaces!

Handlers

Well, you should have just about gutted ch3shortener.handler by now. If you've copied out (but not deleted) app-routes and app, it's time to get rid of them. Here's what handler.clj looks like now.

(ns ch3shortener.handler
  (:require [ring.util.request :as req]
            [ring.util.response :as res]))

You need to be prepared to deal with requests and responses, but there is nothing to do just yet. That's fine, since there will be plenty to do here later. Let's also make sure that handler_test.clj is similarly empty:

(ns ch3shortener.handler-test
  (:require [clojure.test :refer :all]
            [ring.mock.request :as mock]
            [ch3shortener.handler :refer :all]))

Why a Protocol?

Clojure's protocol system is based on, but not identical with, Java's interfaces. Protocols define a set of methods that can have different implementations for different types of data. Since one type can implement any number of different protocols, it also serves as a form of multiple inheritance.

The key feature in this context is the ability to abstract away the exact storage implementation. During early development, it's very convenient to keep your application state in memory—this makes it easy to iterate on schemas and storage methods, simplifies testing, and generally speeds things along.

When you're running into production, however, using in-memory storage is suddenly a huge hindrance. You don't really have data persistence, access can be inefficient, and you don't have all of the features of a proper database.

Using a storage protocol provides the best of both worlds, albeit at a cost. Once you define what it means to be an instance of application storage, you can have a quick and easy implementation that uses a Clojure atom to use during development, then later on when you have a better understanding about the storage contract and requirements, you can write a second implementation using the database of our choice and seamlessly substitute it in. If you're smart about testing, you can even demonstrate that both implementations are functionally interchangeable.

On the other hand, using a storage protocol rather than specific storage functions adds complexity to the sample application, because there is an extra layer of indirection between the application code and the storage code. This makes it impossible for your editor or IDE to jump directly to the implementation of a storage method, since it won't be resolved until runtime. It also introduces the possibility for divergence between implementations, which is a very pernicious form of technical debt.

These drawbacks apply to protocols in general, and we urge you to think pretty hard about whether a protocol is really necessary for any given task. That said, it's almost always a good idea to use a protocol for storage in a stateful web service like this one, unless you're absolutely sure you'll only ever need one storage implementation.

Creating the Storage Protocol

Our storage protocol is not a handler, a route, or an application, so you need a new namespace. Let's create src/ch3shortener/storage.clj:

(ns ch3shortener.storage)
(defprotocol Storage
  )

Pause for a moment to think about what you need from storage:

• Create a link with the supplied ID and URL.
• Retrieve a link, given its ID.
• Update a link, given its ID and URL.
• Delete a link, given its ID.
• List all known links.

Translate them into five storage methods:

(defprotocol Storage
  (create-link [this id url]
    "Store the url under the id. Returns the id if successful, nil if the id is
      already in use.")
  (get-link [this id]
    "Given an ID, returns the associated URL. Returns nil if there is no associated
       URL.")
  (update-link [this id new-url]
    "Updates id to point to new-url. Returns the id if successful, nil if the id
      has not yet been created.")
  (delete-link [this id]
    "Removes a link with the given ID from storage, if it exists.")
  (list-links [this]
    "Returns a map of all known IDs to URLs."))

Testing Protocol Implementations

Even though you can't really test a protocol without an implementation, it's not too early to start writing tests. You know it's important to use tests to show the equivalence of different protocol implementations, and writing these tests ahead of time will help guide the development of your in-memory storage implementation.

The point of using a protocol is to avoid worrying too much about individual implementations, and testing should reflect that. The same exact tests should pass, regardless of the underlying implementation, or else there's probably something wrong. The key here is to write a testing function, rather than a normal test expression. Let's create test/ch3shortener/storage_test.clj:

(ns ch3shortener.storage-test
  (:require [ch3shortener.storage :refer :all]
            [clojure.test :refer :all]))
(defn is-valid-storage ;; note, not deftest
  "Given an implementation of the Storage protocol, assert that it fulfills the
  contract."
  [stg]
  (let [url "http://example.com/clojurebook"
        id "book"]
    (testing "can store and retrieve a link"
      (testing "create-link returns the id"
        (is (= id (create-link stg id url)))
        (testing "and it won't overwrite an existing id"
          (is (nil? (create-link stg id "bogus")))
          (is (= url (get-link stg id))))))
    (testing "can update a link"
      (let [new-url "http://example.com/nevermind"]
        (update-link stg id new-url)
        (is (= new-url (get-link stg id)))))
    (testing "can delete a link"
      (delete-link stg id)
      (is (nil? (get-link stg id)))))
  (testing "can list all links"
    (let [id-urls {"a" "http://example.com/a"
                   "b" "http://example.com/b"
                   "c" "http://example.com/c"}
          ids (doseq [[id url] id-urls]
                (create-link stg id url))
          links (list-links stg)]
      (testing "in a map"
        (is (map? links))
        (testing "equal to the links we created"
          (is (= id-urls links)))))))

It may seem strange that the function's name starts with is, but it's helpful for functions that contain is assertions to be marked this way. You can choose to define a valid-storage predicate that returns true or false, but then you lose granularity that comes from having separate assertions for each of the expected behaviors.

The is-valid-storage function won't do anything until you call it, so the tests will continue to pass for now. But once you do have a concrete storage implementation, you will need to call this function in a deftest form and then know if it passes. For now, keep this around and you can use it for reference while writing the in-memory implementation.

In-Memory Storage

It's time to write a storage implementation. You can put this in the existing storage namespace, but it's a good idea to keep each implementation separate. Let's create src/ch3shortener/storage/in_memory.clj:

(ns ch3shortener.storage.in-memory
  (:require [ch3shortener.storage :refer :all]))

You can implement each storage method inline in one big reify expression, but that would be pretty hard to read. Instead, let's write functions for each storage method one at a time, using the method* naming convention so you don't clash with the storage methods themselves. Each of the functions takes a storage atom (!stg) as a parameter, and most also take a url and/or id.

First, let's handle create-link:

(defn create-link*
  [!stg id url]
  (when-not (contains? @!stg id)
    (swap! !stg assoc id url)
    id))

Remember to check first to see whether the id is already in storage, and if not then nil will be returned. The when-not macro is a big help here, and it also tells later developers that the function could return nil.

Let's move on to get-link, which is almost embarrassingly simple:

(defn get-link*
  [!stg id]
  (get @!stg id))

The storage contract specifies that get-link can return nil, so use get without the optional not-found argument. The update-link implementation is a nice mirror image of create-link:

(defn update-link*
  [!stg id url]
  (when (contains? @!stg id)
    (swap! !stg assoc id url)
    id))

This changes when-not to when, since the methods have opposite requirements. Let's move on to delete-link:

(defn delete-link*
  [!stg id]
  (swap! !stg dissoc id)
  nil)

There's no need to check whether the link actually exists, just simply ensure that it doesn't. Returning nil at the end isn't strictly required, but otherwise swap! will return the entire link map, which is not helpful.

Our last storage method to implement is also the simplest:

(defn list-links*
  [!stg]
  @!stg)

You can do something even shorter, like (def list-links* deref), but this definition is clearer.

Finally, it's time to write a constructor for the storage implementation. The plan here is to construct a blank storage atom and close over it with reify:

(defn in-memory-storage
  []
  (let [!stg (atom {})]
    (reify Storage
      (create-link [_ id url] (create-link* !stg id url))
      (get-link [_ id] (get-link* !stg id))
      (update-link [_ id url] (update-link* !stg id url))
      (delete-link [_ id] (delete-link* !stg id))
      (list-links [_] (list-links* !stg)))))

The reify function takes a protocol and some number of method definitions and returns an object with those defined methods. Since the !stg atom is in scope when reify is called, each of those methods will keep a reference to it for the lifetime of the storage object.

The constructor takes no options, but that's just because it's the simplest possible working storage implementation. A more realistic option for production use involves a database, and the constructor needs to take parameters for at least the database host and credentials. In a typical application, those credentials would come from environment variables and read at runtime using a library like environ.

Now you can test this using the is-valid-storage function defined earlier. Add the following to the end of test/ch3shortener/storage_test.clj:

(deftest in-memory-storage-test
  (let [stg (in-memory/in-memory-storage)]
    (is-valid-storage stg)))

Three leisurely lines is all it takes now to test a new storage implementation! It's unlikely that this form will change; instead, new tests should go in the is-valid-storage function to enforce consistency across implementations.

Separating storage into its own protocol is great for flexibility and it enforces a strict separation of concerns. The rest of the sample application can only use storage methods that are defined (and hopefully tested) ahead of time. Testing storage implementations with a single function provides assurance of consistency while minimizing code duplication.

get-link

The get-link handler should take an id and return one of two possible responses:

• If the link is found in storage, return a 302 redirect to the URL.
• If the link is not found, return a 404 response.

First, let's require the storage namespace in order to use storage methods:

(ns ch3shortener.handler
  (:require [ring.util.request :as req]
            [ring.util.response :as res]
            [ch3shortener.storage :as st]))

Now implement get-link, using ring.util.response helpers to do most of the work:

(defn get-link
  [stg id]
  (if-let [url (st/get-link stg id)]
    (res/redirect url)
    (res/not-found "Sorry, that link doesn't exist.")))

You may notice that this is more of a "handler" than a handler. That is to say, it doesn't take a full request object, just a link ID. That's okay; you just need to make sure to call it the right way when you add a route for it later on.

Let's add a test to handler_test.clj to make sure that this does what it should. For this test you need a storage object, so you'll also need to require the in-memory-storage function and the storage namespace:

(ns ch3shortener.handler-test
  (:require [clojure.test :refer :all]
            [ring.mock.request :as mock]
            [ch3shortener.handler :refer :all]
            ;; add the following two requirements
            [ch3shortener.storage.in-memory :refer [in-memory-storage]]
            [ch3shortener.storage :as st]))
(deftest get-link-test
  (let [stg (in-memory-storage)
        id "test"
        url "http://test.gov"]
    ;; store a link directly for the test
    (st/create-link stg id url)
    (testing "when the ID exists"
      (let [response (get-link stg id)]
        (testing "the result is a 302"
          (is (= 302 (:status response)))
          (testing "with the expected URL in the Location header"
            (is (= url (get-in response [:headers "Location"])))))))
    (testing "when the ID does not exist"
      (let [response (get-link stg "bogus")]
        (testing "the result is a 404"
          (is (= 404 (:status response))))))))

The tests pass, so you are on the right track. Let's move on to the next handler, create-link.

create-link

This handler takes a response with a POST body and returns one of two responses:

• If the ID isn't taken, return a 200 response with the short URL.
• If the ID is taken, return a 422 (unprocessable) response.

(defn create-link
  [stg id {url :body}]
  (if (st/create-link stg id url)
    (res/response (str "/links/" id))
    (-> (format "The id %s is already in use." id)
      res/response
      (res/status 422))))

Testing this can be awkward because it reads the body as if it's a string, but there is no middleware in place yet to make that happen. For the purposes of testing the handler, let's stringify the body by adding this test to handler_test.clj:

(deftest create-link-test
  (let [stg (in-memory-storage)
        url "http://example.com"
        request (-> (mock/request :post "/links/test" url)
                  ;; since we haven't added middleware yet
                  (update :body slurp))]
    (testing "when the ID does not exist"
      (let [response (create-link stg "test" request)]
        (testing "the result is a 200"
          (is (= 200 (:status response)))
          (testing "with the expected body"
            (is (= "/links/test" (:body response))))
          (testing "and the link is actually created"
            (is (= url (st/get-link stg "test")))))))
    (testing "when the ID does exist"
      (let [response (create-link stg "test" request)]
        (testing "the result is a 422"
          (is (= 422 (:status response))))))))

With these tests passing, it's one more handler down, and three to go.

update-link

The update-link handler should have a very similar form to create-link. It should take an ID and a body containing a URL, then:

• If the ID exists in storage, return a 200 with the shortened URL.
• If the ID doesn't exist in storage, return a 404 response.

(defn update-link
  [stg id {url :body}]
  (if (st/update-link stg id url)
    (res/response (str "/links/" id))
    (-> (format "There is no link with the id %s." id)
      res/not-found)))

As promised, this is extremely similar to the create-link handler. The tests will also be pretty similar, including the :body workaround:

(deftest update-link-test
  (let [stg (in-memory-storage)
        url "http://example.com"
        request (-> (mock/request :put "/links/test" url)
                  ;; since we haven't added middleware yet
                  (update :body slurp))]
    (testing "when the ID does not exist"
      (let [response (update-link stg "test" request)]
        (testing "the result is a 404"
          (is (= 404 (:status response))))))
    (testing "when the ID does exist"
      (st/create-link stg "test" url)
      (let [new-url "http://example.gov"
            request (assoc request :body new-url)
            response (update-link stg "test" request)]
        (testing "the result is a 200"
          (is (= 200 (:status response)))
          (testing "with the expected body"
            (is (= "/links/test" (:body response))))
          (testing "and the link is actually updated"
            (is (= new-url (st/get-link stg "test")))))))))

Testing the handlers directly can really pay off later. If you run into a problem while testing the full application, the status of the handler tests will tell you a lot about what might be causing the failures.

delete-link

This is another pseudo-handler, since it only needs the storage object and link ID. It also can't really fail, so don't worry about an error response. Since you won't have any useful information to report back to the caller, just return a 204 (no content) response. Here's a nice, quick implementation:

(defn delete-link
  [stg id]
  (st/delete-link stg id)
  (-> (res/response "")
    (res/status 204)))

Note, the empty string is returned, rather than omitting the body entirely. This is standard practice for responses that don't have a body. The tests are just a little bit more involved:

(deftest delete-link-test
  (let [stg (in-memory-storage)
        id "test"
        url "http://example.com/foo"]
    (testing "when the link exists"
      (st/create-link stg id url)
      (let [response (delete-link stg id)]
        (testing "the response is a 204"
          (is (= 204 (:status response))))
        (testing "the link is deleted"
          (is (nil? (st/get-link stg id))))))
    (testing "when the link does not exist"
      (let [response (delete-link stg "bogus")]
        (testing "the response is still 204"
          (is (= 204 (:status response))))))))

You're almost done writing the handlers, but there is still one more to go.

list-links

This handler is going to return a JSON response, so it's time to add a couple of new dependencies to project.clj:

  :dependencies [[org.clojure/clojure "1.7.0"]
                 [compojure "1.4.0"]
                 [ring/ring-defaults "0.1.5"]
                 ;; add these two:
                 [ring/ring-json "0.4.0"]
                 [cheshire "5.5.0"]]

Both of these libraries were mentioned before, but to review: The ring/ring-json library contains middleware that you can use to help return a JSON response, while cheshire is a more general-purpose JSON library that you'll be using in tests.

Let's require wrap-json-response in the handler namespace first:

(ns ch3shortener.handler
  (:require [ring.util.request :as req]
            [ring.util.response :as res]
            [ring.middleware.json :refer [wrap-json-response]] ;; new line
            [ch3shortener.storage :as st]))

Since there is a plan to have one JSON route, you might as well wrap the handler directly, so let's write the final handler:

(defn list-links
  "Returns a handler! Call the handler if you want a response."
  [stg]
  (wrap-json-response
   (fn [_] ;; we don't need the request at this point
     (res/response (st/list-links stg)))))

This function is definitely a little odd, since it closes over the storage object and returns a handler, so calling the handler is going to take some extra parentheses. The advantage to doing it this way is that you can wrap the inner handler with wrap-json-response directly, avoiding any need to manually encode the body or set the content type. All you have to do is put the map into the response body and you're done.

Let's have a look at the tests. First, add one more dependency to the handler-test namespace:

(ns ch3shortener.handler-test
  (:require [clojure.test :refer :all]
            [ring.mock.request :as mock]
            [ch3shortener.handler :refer :all]
            [ch3shortener.storage.in-memory :refer [in-memory-storage]]
            [ch3shortener.storage :as st]
            [cheshire.core :as json])) ;; add this

Use cheshire to decode the response from the new handler. After that, add the list-links-test to the end of the namespace:

(deftest list-links-test
  (let [stg (in-memory-storage)
        id-urls {"a" "http://link.to/a"
                 "b" "http://link.to/b"
                 "c" "http://link.to/c"}]
    (doseq [[id url] id-urls]
      (st/create-link stg id url))
    (let [handler (list-links stg)
          response (handler (mock/request :get "/links"))
          parsed-links (json/decode (:body response))]
      (testing "the response is a 200"
        (is (= 200 (:status response))))
      (testing "with a body that decodes to the original map"
        (is (= id-urls parsed-links))))))

Note how we're calling (list-links stg) to get the handler, not a response. Proceed to call the handler with the kind of request expected (even though it doesn't use the request), and then parse the response as JSON.

The first, last, and most important thing to remember about handlers is that they are ordinary Clojure functions that take and return maps. The Clojure standard library comes with dozens of functions that work on maps, and those functions can help you write handlers. Additionally, Ring itself comes with a wealth of useful handler-specific functions, found in ring.util.request and ring.util.response.

POST /links/:id

Let's start with the C in CRUD, POST /links/:id. The handler written for this endpoint takes an ID and the request body, but the body has to be turned into a string first. Let's add the route and the middleware to shortener-routes:

(defn shortener-routes
  [stg]
  (-> (routes
       (POST "/links/:id" [id :as request] (handler/create-link stg id request))
       (route/not-found "Not Found"))
    (wrap-routes mw/wrap-slurp-body)))

The create-link handler takes both the id and the full request map, so grab the former by matching on its name in the binding vector and the latter using :as destructuring.

Notice that you're indiscriminately wrapping everything with wrap-slurp-body for now, and that you're using wrap-routes to do it. With these tests it's safe to use wrap-slurp-body, but you need to use wrap-routes to make sure the middleware only gets called when a route matches. Otherwise, you're risking destroying the contents of a request body.

In terms of tests, make sure that the route is matching and behaving somewhat expectedly. Let's add a simple example to the ch3shortener.application-test namespace:

(deftest test-app
  (let [url "http://example.com/post"
        id "test"
        path (str "/links/" id)]
    (testing "creating a link"
      (let [response (app (mock/request :post path url))]
        (is (= 200 (:status response)))
        (is (= path (:body response))))))
  (testing "not-found route"
    (let [response (app (mock/request :get "/invalid"))]
      (is (= (:status response) 404))))) 

You don't have a way to test whether creating the link is effective yet, but you will soon. Until then, the fact that the handler and the storage layer are both tested should give you some confidence that things are going well.

GET /links/:id

Now that you can create short links, it's time to actually use them. Let's add a route that will redirect you to the URL you want when you give it a short link ID. Add this to shortener-routes:

(defn shortener-routes
  [stg]
  (-> (routes
       (POST "/links/:id" [id :as request] (handler/create-link stg id request))
       (GET "/links/:id" [id] (handler/get-link stg id))
       (route/not-found "Not Found"))
    (wrap-routes mw/wrap-slurp-body)))

Augment the tests to verify that both link creation and retrieval work:

(deftest test-app
  (let [url "http://example.com/post"
        id "test"
        path (str "/links/" id)]
    (testing "creating a link"
      (let [response (app (mock/request :post path url))]
        (is (= 200 (:status response)))
        (is (= path (:body response)))))
    (testing "visiting a link"
      (testing "when the link exists"
        (let [response (app (mock/request :get path))]
          (testing "returns a 302"
            (is (= 302 (:status response)))
            (testing "with the correct location"
              (is (= url (get-in response [:headers "Location"])))))))
      (testing "when the link does not exist"
        (let [response (app (mock/request :get "/links/nothing"))]
          (testing "returns a 404"
            (is (= 404 (:status response))))))))
  (testing "not-found route"
    (let [response (app (mock/request :get "/invalid"))]
      (is (= (:status response) 404)))))

This is called an MVP (Minimum Viable Product). You can now shorten a link and redirect to it when asked to do so. You still need to implement updating, deleting, and listing.

PUT /links/:id

It's time to implement the mirror-universe version of link creation: link updating. This should be easy since it's so similar to POST /links/:id. Just add this line to shortener-routes:

(defn shortener-routes
  [stg]
  (-> (routes
       (POST "/links/:id" [id :as request] (handler/create-link stg id request))
       (PUT "/links/:id" [id :as request] (handler/update-link stg id request))
         ;; new
       (GET "/links/:id" [id] (handler/get-link stg id))
       (route/not-found "Not Found"))
    (wrap-routes mw/wrap-slurp-body)))

Add this new deftest form to the end of ch3shortener.application-test:

(deftest link-updating
  (let [id "put"
        url "http://example.com/putTest"
        path (str "/links/" id)]
    (testing "when the link does not exist"
      (let [response (app (mock/request :put path url))]
        (testing "the response is a 404"
          (is (= 404 (:status response))))))
    (testing "when the link does exist"
      (app (mock/request :post path "http://example.post"))
      (let [response (app (mock/request :put path url))]
        (testing "the response is a 200"
          (is (= 200 (:status response))))))))

You are now up to CRU on the CRUD scale, so just a little further to go.

DELETE /links/:id

This should be getting routine by now. Add a single line to shortener-routes:

       (DELETE "/links/:id" [id] (handler/delete-link stg id))

And a quick test to make sure it works:

(deftest delete-link
  (let [id "thing"
        url "http://example.com/thing"
        path (str "/links/" id)]
    (testing "when the link doesn't exist"
      (let [response (app (mock/request :delete path))]
        (testing "the result is a 204"
          (is (= 204 (:status response))))))
    (testing "when the link does exist"
      (app (mock/request :post path url))
      (let [response (app (mock/request :delete path))]
        (testing "the response is still a 204"
          (is (= 204 (:status response)))
          (testing "and the link is now a 404"
            (is (= 404 (:status (app (mock/request :get path)))))))))))

GET /links

All right, it's time for the final endpoint in the example service. You may remember that this handler is a little different, because you need to call the function to construct it. Well, thankfully Compojure handles that perfectly well without you having to do anything particularly unusual. Go ahead and add this line somewhere inside shortener-routes:

       (GET "/links" [] (handler/list-links stg))

When Compojure matches this route, it evaluates the form on the right and checks the type of the return value. If it's a function, it assumes that it's a handler and passes it the request map. In this case, the form does evaluate to a handler, so everything's fine.

In order to test this, you'll need cheshire again, so add this line to the application-test namespace declaration:

(ns ch3shortener.application-test
  (:require [ch3shortener.application :refer :all]
            [clojure.test :refer :all]
            [ring.mock.request :as mock]
            [cheshire.core :as json] ;; add this
            [clojure.string :as str]))

Then add this somewhere else in the file:

(deftest list-links
  ;; first make sure there are some links to list
  (let [id-urls {"a" "http://example.com/a"
                 "b" "http://example.com/b"
                 "c" "http://example.com/c"}]
    (doseq [[id url] id-urls]
      (app (mock/request :post (str "/links/" id) url)))
    (let [response (app (mock/request :get "/links"))
          parsed-body (json/decode (:body response))]
      (testing "the response is a 200"
        (is (= 200 (:status response)))
        (testing "and the decoded body contains all of the links we added"
          (is (= id-urls
                 (select-keys parsed-body ["a" "b" "c"]))))))))

That concludes the implementation of the link-shortener, from start to finish. It may be simple, but it has a solid foundation and a well-defined structure that make it a good codebase to iterate on and expand. The minimal storage implementation is ready to be swapped out for something more robust if and when that becomes necessary. The majority of the functions are short and focused, taking ordinary Clojure data as arguments and returning ordinary Clojure data structures, which helps to make it accessible to developers without much specialized experience.

Finally, tests at multiple levels of composition (handlers, middleware, routes) give you confidence that the application works as designed—and they'll help narrow down the root cause if something does show unexpected behavior. If you add other storage implementations, you can test that they truly are interchangeable with just a few lines of code.

If you're feeling up to the challenge, now would be a great time to experiment with adding authentication, writing a new storage implementation, or adding a front end for the service in Clojurescript! There's no substitute for creative tinkering, and now that you understand the fundamentals, you'll be able to take this project in any direction that interests you.

Heroku

Heroku is a PaaS (Platform as a Service) solution for serving web applications written in almost any language, including Clojure. It's a favorite of hobbyists because it offers a free tier that's suitable for personal or demonstration use, but also easily scales up for more serious projects.

Heroku has excellent support for deploying Ring-based Clojure applications like the link shortener from earlier in this chapter. The exact steps for deploying are subject to change at any time, so it's best to follow Heroku's official documentation for Clojure services.

Amazon Elastic Beanstalk

Amazon Elastic Beanstalk is a PaaS offered by Amazon as part of the AWS (Amazon Web Services) collection of products. It doesn't have the same kind of official support for Clojure that Heroku does, but that hasn't stopped the Clojure community from adopting it as a platform.

There are two main approaches to deploying to Elastic Beanstalk. The first takes advantage of Java interoperability to use Amazon's own Java API. The most convenient way to do this is with the lein-beanstalk plugin, which adds new Leiningen tasks for deploying to AWS. Once you add the plugin to your project and provide your AWS credentials, it's as simple as lein beanstalk deploy {environment}.

The second method relies on Docker, a lightweight virtualization technology that relies on the Linux kernel for process isolation rather than running a full virtual machine. Elastic Beanstalk supports running software from Docker containers, so once you containerize your Clojure service you can run it on AWS or several other cloud providers.