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! |
(This is the node.js stack - please see here for installation instructions: node.js & yarn)
Note that step 4 installs it as a command line tool using "yarn link"
Test it out by typing:
reslangThis should bring up the options.
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 --openIf you want just want to print to stdout use:
reslang models/simple-resource --stdoutIf you want to use the Swagger editor, add --web to the cmd line:
reslang models/simple-resource --open --webThen 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 mainThis 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 --eventsIf instead you wish to view the events in the AsyncAPI Playgrounder for editing, please add the --web option.
reslang models/eventing --open --events --webNote 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 --openWill 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.