cognitect-labs.vase

https://github.com/cognitect-labs/vase.git


    git clone 'https://github.com/cognitect-labs/vase.git'
      

      

(ql:quickload :cognitect-labs.vase)

★325

Vase: Data-driven microservices

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.

Major Changes Since v0.9

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 use vase.datomic/query.

Releases and Dependency Information

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>

Before you get started

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

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

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.

Getting Started

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.

Prerequisites

By default, Vase uses an in-memory Datomic database, using the publicly available Datomic-free version located in Clojars.

Run Vase Standalone

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.

Use the template

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/

Adding Vase to an Existing Pedestal project

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))))

Documentation

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

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.

Support

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.