Server-side API's¶
Creating a well-defined API is an excellent way to make a service accessible to the wider world.
Using the OpenAPI specification, APIs provide interactive documentation, making the API more accessible and easier to test.
The ring specification abstracts HTTP requests & responses, automatically converting to and from a Clojure hash-map.
Clojure routing libraries typically take either use a data configuration (e.g. Reitit) or provide a Domain Specific Language (DSL) for defining routes (Compojure).
Practicalli recommends Reitit
There are many excellent routing libraries available for Clojure, however reitit is very well documented and takes a data centric approach.
Practicalli has found reitit easy to work with on new project and for migrate existing project to.
Reitit¶
Reitit is a data defined routing library which can be used with the Ring specification and middleware.
Defining route configuration as data simplifies validation, with errors returned containing clojure.spec information (or Malli).
Routing is bi-directional and the configuration is pre-compiled to be highly efficient at runtime.
- supports ring routing and middleware support (reitit-ring library)
- request and response validation (clojure.spec or Malli library)
- automatic data coercion (customisable)
- swagger-ui (OpenAPI) documentation with custom templates
Compojure¶
The Compojure library provides the defroutes macro and HTTP methods (GET, POST, etc) as a DSL for defining routes.
compojure-api¶
Compojure API library and template provide a quick way to create an API, by extending Compojure features.
Open API¶
A standard way to define and API and create an interactive UI to aid in use and testing.
OpenAPI Initiative is an open standards body that steers the OpenAPI Specification (OAS), which provides a REST API description language as a standard way to describe and consume APIs.
OpenAPI was formally known as Swagger. Swagger and Swagger UI are tools that support the implementation the OpenAPI specification.
An OpenAPI Schema can be defined in an openapi.json or openapi.yaml file.
Version 3.2 is the latest release of OpenAPI specification (February 2025)
OpenAPI UI uses the API code and meta data to produce a customisable web interface for an API, increasing discoverability and enabling testing of that API.
Wikipedia: OpenAPI Specification (OAS)
References¶
- Getting started with Compojure API
ring-swagger- RESTful CRUD APIs Using Compojure-API and Toucan - part1
- RESTful CRUD APIs Using Compojure-API and Toucan - part2
Tools¶
OpenGUI - generate UI from OpenAPI specification OS Forge - write YAML with SwaggerUI preview
Alternatives¶
Prismatic schema - lightweight type system for API definition
A library for declarative data description and validation. Schema validation uses Objects, a lightweight type system, to define the shape of any data that the API will respond with as well as any data that is sent along with a request.