Martian

The HTTP abstraction library for Clojure/Script and Babashka, supporting OpenAPI/Swagger and many HTTP client libraries.

---

Calling HTTP endpoints can be complicated. You have to construct the right URL with the right route parameters, remember what the query parameters are, what method to use, how to encode a request body, coerce a response and many other things that leak into your codebase.

Martian takes a description of these details — either from your OpenAPI/Swagger definition, or just as lovely Clojure data — and provides a client interface to the API that abstracts you away from HTTP and lets you simply call operations with parameters, keeping your codebase clean.

You can bootstrap it in one line and start calling the server:

(require '[martian.core :as martian]
         '[martian.clj-http :as martian-http])

(def m (martian-http/bootstrap-openapi "https://pedestal-api.oliy.co.uk/swagger.json"))

(martian/response-for m :create-pet {:name "Doggy McDogFace" :type "Dog" :age 3})
;; => {:status 201 :body {:id 123}}

(martian/response-for m :get-pet {:id 123})
;; => {:status 200 :body {:name "Doggy McDogFace" :type "Dog" :age 3}}

Implementations for many popular HTTP client libraries are supplied as modules (see below), but any other HTTP library can be used due to the extensibility of Martian's interceptor chain. It also allows custom behaviour to be injected in a uniform and powerful way.

The martian-test module allows you to assert that your code constructs valid requests to remote servers without ever actually calling them, using the OpenAPI/Swagger spec to validate the parameters. It can also generate responses in the same way, ensuring that your response handling code is also correct. Examples are below.

---

Table of Contents

1. Latest versions & API docs
   • Core module
   • Supported HTTP clients
   • Testing and interop libraries
2. Features
3. Basic usage
4. Bootstrapping from local file
5. No Swagger, no problem
6. Handlers validation
7. Idiomatic parameters
8. Parameter defaults
9. Route name sources
10. Built-in media types
11. Response validation
12. Testing with martian-test
    • Generative testing
    • Non-generative testing
13. Recording and playback with martian-vcr
14. Custom behaviour
    • Custom interceptors
      • Global interceptors
      • Per route interceptors
    • Custom coercion matcher
    • Built-in encoders options
    • Custom media types
    • HTTP client-specific options
15. Development mode
16. Java
17. Caveats
18. Development
19. Issues and features
20. Acknowledgements

---

Latest versions & API docs

Core module

Add the required dependency to the core Martian module:

| Core Module | API Docs | | ----------- | -------- | | | |

Supported HTTP clients

Add one more dependency to the module for the target HTTP client library:

| HTTP client | Martian Module | JVM | BB | JS | API Docs | | ----------- | -------------- | --- | -- | -- | -------- | | hato || ✔ | | || | clj-http || ✔ | | || | clj-http-lite || ✔ | ✔ | || | http-kit || ✔ | ✔ | || | bb/http-client || ✔ | ✔ | || | cljs-http || | | ✔ || | cljs-http-promise || | | ✔ ||

Testing and interop libraries

Optionally add dependencies on modules for testing and interop:

| Martian Module | Docs | API Docs | | -------------- | ---- | -------- | | | README | | | | README | | | | README | |

The martian-re-frame integrates Martian event handlers into re-frame, simplifying connecting your UI to data sources.

Features

• Bootstrap from a OpenAPI/Swagger definition, a local file/resource, or provide your own API mapping as data
• Modular with support for many popular HTTP client libraries
• Build URLs and request maps from code or generate and perform the request, returning the response
• Validate requests and responses to ensure they are correct before the data leaves/enters your system
• Explore an API from your REPL
• Extensible via interceptor pattern — inject your own interceptors anywhere in the chain
• Negotiates the most efficient media type — including transit, edn, json and more — and handles both request encoding (serialisation) and response coercion (deserialisation)
• Easy to add support for any other media type or reconfigure encoders for the built-in ones
• Support for integration testing without requiring external HTTP stubs
• Routes are named as idiomatic kebab-case keywords of the endpoint's operationId in the OpenAPI/Swagger definition (default) or generated from the URL (path) pattern, HTTP method, and definition
• Parameters are aliased to kebab-case keywords so that your code remains idiomatic and neat
• Parameter defaults can be optionally applied
• Simple, data driven behaviour with low coupling using libraries and patterns you already know
• Pure client code, no server code or modifications required
• Write generative, realistic tests using [martian-t