Migration Guide to 2.0.0

NOTE: Compojure-api 2.0.0 has not been released yet. For a preview, you can try the Compojure-api 1.2.0 alphas. What was supposed to become Compojure-api 1.2.0 will be released as 2.0.0.

About

Compojure-api 2.0.0 has the following breaking changes:

• Compojure-api 2.0.0 requires Java 1.8 or later (because of Muuntaja).
• We now use Muuntaja instead of ring-middleware-format; :format options need migrating
• Static context calls are optimized in a way that can break some existing code.
• Request and response coercion now depends on the content type.
• swagger-ui and swagger-docs now take options map instead of varargs.
• middleware was removed; use route-middleware instead

The details are below.

NOTE: If you're using version older than 1.1.x, please first upgrade to 1.1.10 (the last pre-2.0.0 version) before upgrading to 2.0.0. If you're using pre-1.0.0 version, see the migration guide to 1.0.0.

• See also the full CHANGELOG.

Muuntaja

We now use Muuntaja instead of ring-middleware-format for format negotiation, encoding, and decoding. In benchmarks, Muuntaja is much faster than ring-middleware-format.

• The api option :format has been removed. Use :formats instead. It should be either a Muuntaja instance, Muuntaja options map, or nil to disable Muuntaja.
• See the instructions for configuring Muuntaja.
• If you haven't configured :format, you do not need to do anything.

Static context optimization

If your context is static (there are no route parameters), it's evaluated only once. This makes it faster, but code like this won't work as expected:

(context "/static" []
  (if (its-noon?)
    (GET "/noon-route" [] (ok "it's noon")))

In this case, replace context with dynamic-context. If you're unsure, you can replace any context calls with dynamic-context. This gives you the same behavior and performance as context in Compojure-api 1.1.

Request and response coercion

Request and response coercion now depends on the format negotiated by Muuntaja. The old default was to coerce all requests and responses with json-coercion-matcher. The new defaults are as follows:

Format	Request	Response
application/edn	validate	validate
application/transit+json	validate	validate
application/transit+msgpack	validate	validate
application/json	json-coercion-matcher	validate
application/msgpack	json-coercion-matcher	validate
application/x-yaml	json-coercion-matcher	validate

• If you have custom coercions, they should continue to work as before.
• default-coercion-matchers has been replaced by default-coercion-options.

swagger-ui and swagger-docs

swagger-ui and swagger-docs now take an options map with a path key instead of an optional path and vararg options.

;; Compojure-api 1.1
(swagger-ui "/swagger")

;; Compojure-api 2.0
(swagger-ui {:path "/swagger"})

swagger-routes and :swagger api options work as before.

middleware and route-middleware

middleware has been removed, because it dangerously applied the middleware even to requests that didn't match the contained routes. Replace it with compojure.api.core/route-middleware, which only applies middlewares when the request is matched against the contained routes.

Still having problems?

If you need help, find us on #ring-swagger in Clojurians Slack (join) or open an issue. If this guide is missing something relevant, feel free to update it. All feedback welcome.