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:
vase/query
,
for example, you'll now use vase.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.3"]
Maven dependency information:
<dependency>
<groupId>com.cognitect</groupId>
<artifactId>pedestal.vase</artifactId>
<version>0.9.3</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:
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:
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))))
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.