isabella232 / reslang

A language for describing resource-oriented APIs & turning them into Swagger or resource diagrams. Oriented around the concepts we want to expose in the APIs.

Reslang: API definitions made easy

Reslang is a simple language for describing resource-oriented APIs & turning them into Swagger. It produces Swagger/OpenAPI which is fully aligned with LiveRamp's API standards.

It can also generate an AsyncAPI specification, describing events, from the same spec. Recently we have added the ability to generate JSON schema from the Reslang spec too.

Release notes

Reslang is licensed under Apache V2

Docs

Topic	Description
Why reslang?	Why do we need this tool and what does it offer?
Intro tutorial	Describes making a toy API for manipulating files and directories.
The API paradigm	What is the Reslang paradigm and how does it relate to REST, OO and RPC
Event intro tutorial	Describes a simple example of how to generate AsyncAPI to describe events
Sections	This explains how to reorder / group the presentation of your resources
Direct2Dist API	This is a more complex example which recreates the entire Direct2Dist API.
MULTI verbs	Describes MULTI- verbs such as MULTIPOST, MULTIPATCH etc
Reference manual	This describes the syntax and features in more depth.
Server blocks	This explains how to define servers for REST and events APIs
JSON schema generation	This explains how to generate JSON schema definitions from Reslang code
Internal System Design	Explains how Reslang is structured as a typescript application, and how the transpiler works
VSCode Syntax highlighting	Explains how to install VSCode syntax highlighting. Hint search extensions for Reslang!

Installation

For local use

1. ensure node & yarn are installed

(This is the node.js stack - please see here for installation instructions: node.js & yarn)

2. clone the reslang repo
3. yarn install
4. ./install-reslang

Note that step 4 installs it as a command line tool using "yarn link"

Running

Test it out by typing:

reslang

This should bring up the options.

Click to see Installation options

Running in Docker (for internal LiveRamp users only)

Individuals who do not want to build Reslang from scratch are free to use the reslang-docker script which provides convenient, but limited, functionality with a reslang container. This script outputs the generated swagger to STDOUT and requires an absolute path to function.

    bash ./reslang-docker.sh $PWD/models/distribution

Creating & viewing the Swagger / OpenAPI

To create swagger, you first create a reslang file. Then you simply ask the reslang program to turn this into swagger.

Note that the models directory has a set of example definitions.

The following copies the swagger to the clipboard and opens the ReDoc browser for you.

reslang models/simple-resource --open

If you want just want to print to stdout use:

reslang models/simple-resource --stdout

Viewing Swagger / OpenAPI in Swagger editor

If you want to use the Swagger editor, add --web to the cmd line:

reslang models/simple-resource --open --web

Then paste the clipboard into the left window pane of the editor.

Creating a graphical view

Reslang can generate dotviz output, which provides a nice graphical view of the resources.

The following command will copy the dotviz output to the clipboard.

reslang models/simple-resource --open --diagram main

This will open your browser at a nice graphviz online editor. Paste the clipboard into the editor and you will get your graphical view of your API - a resource diagram.

Viewing events via AsyncAPI

Reslang can generate AsyncAPI, describing the events a REST API can generate. It also provides an "event" keyword which you can use to describe adhoc events.

reslang models/eventing --open --events

If instead you wish to view the events in the AsyncAPI Playgrounder for editing, please add the --web option.

reslang models/eventing --open --events --web

Note that the AsyncAPI spec has been copied to the clipboard - you will need to paste it into the opened editor, on the left.

Pretty Printing - Stripping out the comments for review

Reslang can produce a nice pretty-printed, stripped down version of the Reslang in html. It is often easier to review this form, as it removes the comments and error structures.

reslang models/resources --stripped --open

Will open a browser on the stripped down file. If you just want plain text, add --plain

Requesting new features

New features and enhancements that involve changing LiveRamp's API standards will not be considered until the API standards proposal process is complete.

Other enhancements should be requested by opening a GitHub Issue using the appropriate issue template or by opening a Pull Request and having your changes reviewed by the API Squad.