Hello! This is a sketch for a new internal representation of API schemas for mocking.
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
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.
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
.
First, install ReasonML and build the spec.
cd reasonml
npm install -g bs-platform
npm run build
cd reasonml
node src/Spec.bs.js
Purescript is basically the same as ReasonML. Slightly less modern looking, but the language allows you to do a lot more.
First, install purescript and build the spec.
cd purescript
npm install -g purescript
npm install -g spago
spago install
spago build
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 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.
First, install stak:
curl -sSL https://get.haskellstack.org/ | sh
Then:
cd haskell
stack setup
stack build
cd haskell
stack exec gemara-exe
F# resembles ReasonML.
None, but be sure to install the dotnet
framework.
cd fsharp
dotnet run