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.
Reslang is licensed under Apache V2
| 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! |
- ensure node & yarn are installed
(This is the node.js stack - please see here for installation instructions: node.js & yarn)
- clone the reslang repo
- yarn install
- ./install-reslang
Note that step 4 installs it as a command line tool using "yarn link"
Test it out by typing:
reslang
This should bring up the options.
Click to see Installation options
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
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
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.
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.
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.
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
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.