{"id":36471601,"url":"https://github.com/liveramp/reslang","last_synced_at":"2026-01-12T00:39:08.515Z","repository":{"id":37790635,"uuid":"195102746","full_name":"LiveRamp/reslang","owner":"LiveRamp","description":"A language for describing resource-oriented APIs \u0026 turning them into Swagger or resource diagrams. Oriented around the concepts we want to expose in the APIs.","archived":false,"fork":false,"pushed_at":"2025-10-22T07:41:32.000Z","size":8160,"stargazers_count":24,"open_issues_count":28,"forks_count":7,"subscribers_count":75,"default_branch":"master","last_synced_at":"2025-10-22T09:26:32.946Z","etag":null,"topics":["api","api-documentation","api-lifecycle-management","api-modeling","api-rest","asyncapi","documentation-generator","domain-driven-design","events","json","openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LiveRamp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-07-03T17:51:56.000Z","updated_at":"2025-10-22T07:29:24.000Z","dependencies_parsed_at":"2023-11-27T16:02:14.233Z","dependency_job_id":"7be7a35a-81cc-44b8-899c-f1ed2c631075","html_url":"https://github.com/LiveRamp/reslang","commit_stats":{"total_commits":199,"total_committers":23,"mean_commits":8.652173913043478,"dds":0.6683417085427136,"last_synced_commit":"f8af0dbdcd8299b9df415a9bcaa8bd1f6bc0b13f"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/LiveRamp/reslang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveRamp%2Freslang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveRamp%2Freslang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveRamp%2Freslang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveRamp%2Freslang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LiveRamp","download_url":"https://codeload.github.com/LiveRamp/reslang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveRamp%2Freslang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28329806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-documentation","api-lifecycle-management","api-modeling","api-rest","asyncapi","documentation-generator","domain-driven-design","events","json","openapi","openapi3","swagger"],"created_at":"2026-01-12T00:39:07.864Z","updated_at":"2026-01-12T00:39:08.507Z","avatar_url":"https://github.com/LiveRamp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reslang: API definitions made easy\n\nReslang is a simple language for describing resource-oriented APIs \u0026 turning them into Swagger. It produces Swagger/OpenAPI which is fully aligned with [LiveRamp's API standards](https://liveramp.atlassian.net/wiki/spaces/CI/pages/1014498273/RFC+API-3+LiveRamp+API+Standards).\n\nIt can also generate an [AsyncAPI specification](https://www.asyncapi.com/), describing events, from the same spec. Recently we have added the ability to generate [JSON schema](https://json-schema.org/) from the Reslang spec too.\n\n[Release notes](./docs/releases.md)\n\nReslang is licensed under [Apache V2](https://www.apache.org/licenses/LICENSE-2.0)\n\n## Docs\n\n| Topic                                                    | Description                                                                                  |\n| -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| [Why reslang?](./docs/why.md)                            | Why do we need this tool and what does it offer?                                             |\n| [Intro tutorial](./docs/intro.md)                        | Describes making a toy API for manipulating files and directories.                           |\n| [The API paradigm](./docs/paradigm.md)                   | What is the Reslang paradigm and how does it relate to REST, OO and RPC                      |\n| [Event intro tutorial](./docs/intro-events.md)           | Describes a simple example of how to generate AsyncAPI to describe events                    |\n| [Sections](./docs/sections.md)                           | This explains how to reorder / group the presentation of your resources                      |\n| [Direct2Dist API](./docs/direct2dist-explanation.md)     | This is a more complex example which recreates the entire Direct2Dist API.                   |\n| [MULTI verbs](./docs/multi.md)                           | Describes MULTI- verbs such as MULTIPOST, MULTIPATCH etc                                     |\n| [Reference manual](./docs/reference.md)                  | This describes the syntax and features in more depth.                                        |\n| [Server blocks](./docs/server-blocks.md)                 | This explains how to define servers for REST and events APIs                                 |\n| [JSON schema generation](./docs/jsonschema.md)           | This explains how to generate JSON schema definitions from Reslang code                      |\n| [Internal System Design](./docs/ReslangSystemDesign.pdf) | Explains how Reslang is structured as a typescript application, and how the transpiler works |\n| [VSCode Syntax highlighting](./vscode/README.md)         | Explains how to install VSCode syntax highlighting. Hint search extensions for Reslang!      |\n\n## Installation\n\n### For local use\n\n1. ensure node \u0026 yarn are installed\n\n(This is the node.js stack - please see here for installation instructions: [node.js](https://nodejs.org/en/download/) \u0026 [yarn](https://classic.yarnpkg.com/en/docs/install/#mac-stable))\n\n2. clone the reslang repo\n3. yarn install\n4. ./install-reslang\n\nNote that step 4 installs it as a command line tool using \"yarn link\"\n\n## Running\n\nTest it out by typing:\n\n    reslang\n\nThis should bring up the options.\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to see Installation options\u003c/summary\u003e\n\n## Running in Docker (for internal LiveRamp users only)\n\nIndividuals 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.\nThis script outputs the generated swagger to STDOUT and requires an absolute path to function.\n\n```\n    bash ./reslang-docker.sh $PWD/models/distribution\n```\n\n\u003c/details\u003e\n\n## Creating \u0026 viewing the Swagger / OpenAPI\n\nTo create swagger, you first create a reslang file. Then you simply ask the reslang program to turn this into swagger.\n\nNote that the models directory has a set of example definitions.\n\nThe following copies the swagger to the clipboard and opens the ReDoc browser for you.\n\n    reslang models/simple-resource --open\n\nIf you want just want to print to stdout use:\n\n    reslang models/simple-resource --stdout\n\n## Viewing Swagger / OpenAPI in Swagger editor\n\nIf you want to use the Swagger editor, add --web to the cmd line:\n\n    reslang models/simple-resource --open --web\n\nThen paste the clipboard into the left window pane of the editor.\n\n## Creating a graphical view\n\nReslang can generate dotviz output, which provides a nice graphical view of the resources.\n\nThe following command will copy the dotviz output to the clipboard.\n\n    reslang models/simple-resource --open --diagram main\n\nThis 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.\n\n## Viewing events via AsyncAPI\n\nReslang 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.\n\n    reslang models/eventing --open --events\n\nIf instead you wish to view the events in the AsyncAPI Playgrounder for editing, please add the --web option.\n\n    reslang models/eventing --open --events --web\n\nNote that the AsyncAPI spec has been copied to the clipboard - you will need to paste it into the opened editor, on the left.\n\n## Pretty Printing - Stripping out the comments for review\n\nReslang 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.\n\n    reslang models/resources --stripped --open\n\nWill open a browser on the stripped down file. If you just want plain text, add --plain\n\n## Requesting new features\n\nNew features and enhancements that involve changing LiveRamp's API standards\nwill not be considered until the [API standards proposal process][standards process] is complete.\n\nOther enhancements should be requested by opening a GitHub Issue using the\nappropriate issue template or by opening a Pull Request and having your changes\nreviewed by the API Squad.\n\n[standards process]: https://docs.google.com/document/d/1X3fcFYLdsRzsQeX89zdmCOoisNsD6X-wcrtYcb8MkGA/edit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliveramp%2Freslang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliveramp%2Freslang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliveramp%2Freslang/lists"}