Tutorial

compojure-api provides a powerful and easy to use way to build web APIs declaratively, with all kinds of fun stuff for free, like Schema validation and interactive Swagger docs. We're going to get started by building a simple API for rolling dice on the internet.

Getting Started

compojure-api provides a handy Leiningen template, so to start off with, let's run lein:

lein new compojure-api dice-api

If we navigate into our newly created dice-api directory, it should look something like this:

.
├── README.md
├── project.clj
└── src
    └── dice_api
        └── handler.clj

Let's open up handler.clj in our editor and take a look at what we start off with.

(ns dice-api.handler
  (:require [compojure.api.sweet :refer :all]
            [ring.util.http-response :refer :all]
            [schema.core :as s]))

(s/defschema Pizza
  {:name s/Str
   (s/optional-key :description) s/Str
   :size (s/enum :L :M :S)
   :origin {:country (s/enum :FI :PO)
            :city s/Str}})

(def app
  (api
    {:swagger
     {:ui "/"
      :spec "/swagger.json"
      :data {:info {:title "Dice-api"
                    :description "Compojure Api example"}
             :tags [{:name "api", :description "some apis"}]}}}

    (context "/api" []
      :tags ["api"]

      (GET "/plus" []
        :return {:result Long}
        :query-params [x :- Long, y :- Long]
        :summary "adds two numbers together"
        (ok {:result (+ x y)}))

      (POST "/echo" []
        :return Pizza
        :body [pizza Pizza]
        :summary "echoes a Pizza"
        (ok pizza)))))

That's a lot of stuff, and a good starting example in and of itself. We can see already an example of a lot of the stuff compojure-api can do. You can see, for instance, the Pizza schema, which we've used to define both an incoming and outgoing query schema for out /echo path.

Let's see how this all works. In your shell, run the following command to fire up the server:

lein ring server

Once it's started, it should open up a browser tab right to the Swagger docs, but if not, you can go to http://localhost:3000/index.html in your browser. It should look something like this:

Not very exciting yet, so we click "Show/Hide", and voila, it's our API!

This is helpfully autogenerated from us from the API we declared. You can click around to play with the template API, in particular, try calling the /echo path with the example input, then try again with one of the keys removed. Hooray for schema validated APIs! Next, we'll get to making our own API.