This is a fork of cognitect-labs/vase which corrects some of the pending issues we have discovered while running in production (i.e. jdk11 compatibility, validate http status codes etc.). This fork will live until the upstream project integrates the necessary fixes.
This system provides a data-driven and extensible way to describe and run HTTP APIs. Building blocks make it very easy to use Datomic as a durable database. Other databases can be added via an extension mechanism.
We learned from using Vase on real-world projects and from hearing feedback in our user community. People like the promise of Vase but found it hard to use.
This release aims to make Vase much easier for common cases:
- A new input format called Fern lets us produce much better error messages when something goes wrong.
- Step-by-step examples show how to grow an API from scratch rather than relying on the Leiningen template.
- A new public API allows applications to skip the files altogether and directly feed Vase with data structures to describe the application. You can produce those however you like, from code, files, values in a database... whatever.
- Datomic has been "demoted" by one namespace level so we can add
support for other external integrations. Instead of
vase/query, for example, you'll now usevase.datomic/query.
If you would like to use the latest developments in Vase, you will need to clone this repository and install it locally:
git clone https://github.com/cognitect-labs/vase
cd vase
lein install
Stable versions are currently deployed to the Clojars repository.
Leiningen dependency information:
[com.cognitect/pedestal.vase "0.9.4"]Maven dependency information:
<dependency>
<groupId>com.cognitect</groupId>
<artifactId>pedestal.vase</artifactId>
<version>0.9.4</version>
</dependency>Vase is built on top of Pedestal and Datomic. While you don't need to be a Pedestal or Datomic expert to use Vase, a little introductory material goes a long way. Newcomers to either will find these resources especially helpful.
Pedestal is a collection of libraries for building services and applications. The core components of Pedestal are Interceptors, the Context Map and the Interceptor Chain Provider.
Interceptors implement functionality and the Context Map controls how Pedestal behaves (i.e., when interceptor chain execution terminates, going async, etc...). The Interceptor Chain Provider connects the interceptor chain to a given platform, creates an initial context and executes the interceptor chain against it. Each interceptor has access to the context map during execution which means that interceptors can alter how Pedestal behaves. What about routes?
Routes are data structures that relate request paths to interceptors. After expansion, They are consumed by a Router which is implemented as an interceptor. When a matching route is found for a given request, the interceptor(s) it relates to are enqueued on the interceptor chain.
Pedestal ships with support for the Jetty, Tomcat and Immutant platforms. Although these are all servlet-based platforms, interceptor providers can be implemented for other platforms.
It should come as no surprise that Pedestal interceptors are a crucial part of Vase so it is helpful to understand what they are and how they work.
As you dive into more advanced Vase usage scenarios, you'll benefit from a deeper understanding of Pedestal. Here's where you should look for more information:
- Pedestal Docs: The Pedestal docs site is a good launching point.
- Pedestal Samples: A collection of samples demonstrating Pedestal's capabilities.
- Pedestal Repository: For those who like to dig into the source.
Datomic is a database of facts and Vase uses it as its backend store. You will immediately be confronted by three Datomic concepts as you work with Vase: schema, query and transaction. Of the three, Datomic queries offer the most variety and, possibly, confusion. Datomic uses a declarative query language called Datomic Datalog for queries. Learn Datalog Today will help you get up to speed with it.
The Datomic docs site has in-depth resources covering schema, query, transactions and more. These are good resources to dive into as you move to more advanced Vase usage scenarios.
Your path to get running depends on what you need to do:
- Just build an API for CRUD operations: Run Vase standalone.
- Integrate with hand-written routes: Add Vase to an existing Pedestal project.
- Use Vase in a new project, for more than just CRUD: Use the template
- Extend Vase with new actions: Create Actions.
By default, Vase uses an in-memory Datomic database, using the publicly available Datomic-free version located in Clojars.
If you just want to run an API that does CRUD (create, read, update,
delete) operations on a database, then you can run Vase
directly. Download the latest uberjar
JAR from Clojars and
use it with java -jar.
java -jar vase-standalone.jar my-service.fern
This path does assume you're using Fern for your input syntax. Vase
will look for the top-level key vase/service in your Fern
environment.
If you want to do more than CRUD, you will need a project. This repository includes a Leiningen template for getting started. Look at the template's README for local/developer setup, otherwise
lein new vase my-service
Look at `my-service/src/
Vase turns API descriptions into Pedestal routes. The API descriptions
specify actions for routes, these are turned into interceptors in the
Pedestal routes. This is done by vase/routes.
vase/routes takes an API base URL and an API specification. The routes it
returns can be used directly by Pedestal like this:
(require '[io.pedestal.http.route.definition.table :as table])
(require '[com.cognitect.vase]))
(defn make-master-routes
[spec]
(table/table-routes
{}
(vase/routes "/api" spec)))The routes that vase/routes returns can also be combined with
hand-written Pedestal routes by concatenating the input to
table/table-routes:
(require '[io.pedestal.http.route.definition.table :as table])
(require '[com.cognitect.vase]))
(defn make-master-routes
[spec]
(table/table-routes
{}
(concat
[["/hello" :get [hello]]]
(vase/routes "/api" spec))))- Adding Vase to an existing Pedestal service
- Building Your First API
- Design document
- Fern Input for Vase - A new way to write descriptors
- Migrating EDN to Fern - Tooling to help port your descriptors
Contributing guidelines for Vase are the same as Pedestal.
For code contribution, you'll need a signed Cognitect Contributor Agreement. For small changes and doc updates, no CA is required.
If you're proposing a significant change, please open an Issue to discuss the design of the change before submitting a Pull Request.
Don't hesitate to reach out if you run into issues or have questions! The Vase community can be found in the the pedestal-users mailing list or the #pedestal slack channel.
Copyright © 2015-2018 Cognitect, Inc. All rights reserved.