routes

Definitions

In order to stub HTTP endpoints you must conform to the route schema. Here's an example:

{ "/something" {:status 200 :body "hello"}
  "/something-else" {:status 201 } }

The key in this map is the request specification and the value is the response specification. The combination of key and value (i.e. request- and response specification) is called a route. You supply this route map to the with-routes! macro or the start! function. For example:

(with-routes! 
      { "/something" {:status 200 :body "hello"}
        "/something-else" {:status 201 } }
      (client/get ...))

Function

As an alternative to explicitly declaring the route map (that consists of one to many routes) you can provide it from a function that takes a server instance as a parameter. This is useful if you need access to some data from the server in order to build up your routes. For example:

(fn [server]
    (let [absolute-uri (str (:uri server) "/somewhere")]
      { "/somewhere" {:status 200 :body absolute-uri}}))

In this example we get the URI of the server (which may be autogenerated if using the macro for later use in our response specification. For example:

(with-routes! 
      (fn [server]
          (let [absolute-uri (str (:uri server) "/somewhere")]
               { "/somewhere" {:status 200 :body absolute-uri}}))
      (client/get ...))

Request Specification

The request specification (the key in the route map) can be created in three different ways:

1. Path only

   This allows you to match a path in the request. For example:

   { "/something" { ... } }

   This will match requests (regardless of http method) whose path is equal to "/something". For example it'll match the URI http://localhost:8083/something but not http://localhost:8083/something2.

2. Map

   If path is not enough it's possible to define the request specification using a map. The schema is defined as this:

   {:path <string>
    :method <any of :get :post :put :delete etc>
    :query-params { :query-param-name <value> }}     

   For example:

   {{:path "/x" :method :get :query-params { :q "query" }} {...} }

   This will match a GET request with path equal to /x that has a query parameter q=query. For example http://localhost:8083/x?q=query. More routing options will be available in the future.

3. Function

   This is the most advanced option and allows you to determine a match based on the actual request by providing a function that returns true or false on match:

   (fn [request] <true or false>)

   The request schema looks like this:

   {:method       <keyword of http method, for example :get :post etc>
    :headers      <map> 
    :content-type <the content-type header>
    :path         <the uri path>
    :request-line <the request line (currently HTTP/1.1 is always added)
    :body         <the request body>
    :query-params <map>

   For example:

   (fn [request]
       (starts-with? (:path request) "/my-resource"))

Response Specification