mikesol / gemara2

Gemara

Hello! This is a sketch for a new internal representation of API schemas for mocking.

Motivation

OpenAPI was never meant as a mocking spec. Only a documentation spec. As a result:

• Difficult to do matching
• Difficult to choose right response
• Difficult to implement logic
• Difficult to store data

Gemara seeks to solve these problems while keeping the main great things about OpenAPI (and even improving them if possible):

• Human readable
• Human writeable
• Unambiguous
• Small surface area

So what is Gemara?

I have no idea. Basically, I've taken an OpenAPI spec and built something that kinda looks like a "standard" in four different languages - ReasonML, F#, Haskell and Purescript. The thought experiment is "Is this a useful representation of an API for mocking?" The specs are applications, meaning in addition to being a spec, they do a small proof-of-concept as a mock when executed.

Original OpenAPI spec

Look here.

ReasonML Experiment

Here it is.

ReasonML has a nice pattern matcher and type safety, making it a good candidate. There are no union types though, so you have to use variants, which leads to the annoying type pathString = PString(string) | PInt(int); instead of something more compact like string | int.

Build

First, install ReasonML and build the spec.

cd reasonml
npm install -g bs-platform
npm run build

Execute

cd reasonml
node src/Spec.bs.js

Purescript Experiment

Here it is.

Purescript is basically the same as ReasonML. Slightly less modern looking, but the language allows you to do a lot more.

Build

First, install purescript and build the spec.

cd purescript
npm install -g purescript
npm install -g spago
spago install
spago build

Execute

Note that this file was written by hand using the Purescript spec, whereas the ReasonML Spec.bs.js is entirely self-contained and doesn't use any hand-wrtten javascript. I could have done the same thing here in Purescript, but I created my own JS file to call the Purescript function spec just to see if I could call Purescript from JavaScript. Turns out to be pretty straightforward - see ./src/Spec.purs.js.

cd purescript
node src/Spec.purs.js   

Haskell experiment

Here it is.

Haskell is basically purescript, but slightly less modern. It is theoretically faster as it is a compiled language, but for this toy example, it doesn't really matter.

Build

First, install stak:

curl -sSL https://get.haskellstack.org/ | sh

Then:

cd haskell
stack setup
stack build

Execute

cd haskell
stack exec gemara-exe

F# experiment

Here it is.

F# resembles ReasonML.

Build

None, but be sure to install the dotnet framework.

Execute

cd fsharp
dotnet run