{"id":29629970,"url":"https://github.com/binarymax/restlang","last_synced_at":"2025-07-21T10:07:56.125Z","repository":{"id":16656359,"uuid":"19411855","full_name":"binarymax/restlang","owner":"binarymax","description":"A Web API description language","archived":false,"fork":false,"pushed_at":"2014-07-19T18:31:42.000Z","size":516,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-10T20:33:01.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://binarymax.com/restlang/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binarymax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-05-03T20:46:53.000Z","updated_at":"2019-08-13T15:40:56.000Z","dependencies_parsed_at":"2022-09-06T10:41:34.475Z","dependency_job_id":null,"html_url":"https://github.com/binarymax/restlang","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/binarymax/restlang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymax%2Frestlang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymax%2Frestlang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymax%2Frestlang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymax%2Frestlang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binarymax","download_url":"https://codeload.github.com/binarymax/restlang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarymax%2Frestlang/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266278415,"owners_count":23904044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-07-21T10:07:55.461Z","updated_at":"2025-07-21T10:07:56.118Z","avatar_url":"https://github.com/binarymax.png","language":"JavaScript","readme":"\u003cimg src=\"https://raw.githubusercontent.com/binarymax/restlang/master/media/logo.png\"\u003e \n\nA cross-compiling DSL (domain specific language) for building APIs\n\n## Hello World\n\n```restlang\n/helloworld\n\nThis API returns a 'Hello World' message!\n\n#Get\n\n\t{/controllers/helloworld.Get}\n\n\t|message string: The text that holds the message\n\t\n```\n\n## Introduction\n\nRestlang is a markdown-inspired language that is used to generate server route specifications, client libraries, testing scripts, and developer documentation for web based APIs.\n\nRestlang defines the 'What' and not the 'How' of APIs. \n\nFor example, you can easily define a Todo list API resource with 50 lines of restlang, and then automatically generate all of the following:\n- The API routes for Node/Express \n- A jQuery AJAX library to consume the above API\n- Integration test scrips for mocha\n- Static HTML documentation files\n\nThe main idea being when an end language target is written, then the end language target works for all APIs defined with Restlang.  Similar to how a markdown parser can target HTML or PDF - once the target is defined it works for all text written in markdown.\n\nAs of writing, only one parser exists and is in development.  This repository holds the restlang.js parser for Node and JavaScript.\n\n## Installation\n\n```\nnpm install restlang\n```\n\nRestlang is currently used in the fullstack generation tool called Realms (https://github.com/binarymax/realms).  It is recommended you read the below documentation before getting started with Realms.\n\n\n### Targets\n\nA Target is an end result output of the Restlang parser coupled with a generator.  Currently only one target generator is supported through Edda [1].\n\n#### _Framework targets_\n\nCurrently, only node is supported as a target through Heimdall[2].  Though Heimdall is semi-mature and in production use, support for Restlang-\u003eHeimdall is experimental.\n\nFuture server framework targets in planning are:\n- Golang\n- PHP\n- Openresty\n- MVC.NET\n\n#### _Client targets_\n\nA nice side effect of having a full parseable API definition, is that client libraries can be generated.  For now, a tool called Bifrost [3] is in development to generate such frameworks, but is not yet ready.\n\nFuture client targets in planning are:\n- iOs\n- Android\n- jQuery\n- Node\n- Golang\n- .NET\n\n#### _Testing targets_\n\nAutomation of Integration Testing is a key goal of Restlang.  Currently only node/mocha is being developed.  See Ragnarok for more information [4]. \n\nAside from Ragnarok there are no other Testing targets planned.\n\n#### _Documentation for Humans target_\n\nThough  mostly human readable in its raw form (again like markdown), a developer documentation target is in the works to generate static documentation HTML.\n\n## Todo Example\n\nHere is an example of a Todo list API in Restlang:\n\n```restlang\n/todo: A Todo list CRUD API\n\n.identity id int64\n\n#Get: Gets a specific To-Do Item\n\n\t{../controllers/todo:Entry}\n\n\t:id int64 required: The ID of the item entry to retrieve\n\n\t|id int64: The ID of the item\n\t|description string: The textual description of the item\n\t|donedate datetime: The date/time when the item was marked as done, null otherwise\n\t|createdate datetime: The date the item was entered into the system\n\t|isdeleted boolean: True if the item has been removed from the list\n\n#Get: Gets a list of Todo Items for a List\n\n\t{../controllers/todo:Collection}\n\n\t?isdone boolean: If true, only return done items, if false only return not done items\n\t?all boolean default false: if true, return all items, done or not\n\n\t|id int64: The ID of the item\n\t|description string: The textual description of the item\n\t|donedate datetime: The date/time when the item was marked as done, null otherwise\n\t|createdate datetime: The date the item was entered into the system\n\t|isdeleted boolean: True if the item has been removed from the list\n\n#Post: Adds a new Todo Item to a List\n\n\t{../controllers/todo:Add}\n\n\t@description string required: The textual description of the item\n\t@donedate datetime: The date/time when the item was marked as done, null otherwise\n\t@createdate datetime: The date the item was entered into the system\n\t@redirect string: Redirect to this URL after Add\n\t\n\t|id int64: The ID of the newly added item\n\t|description string: The textual description of the item\n\t|donedate datetime: The date/time when the item was marked as done, null otherwise\n\t|createdate datetime: The date the item was entered into the system\n\n#Put: Saves a specific Todo Item\n\n\t{../controllers/todo:Save}\n\n\t:id int64 required: The ID of the item entry to save\n\n\t@description string: The textual description of the item\n\t@donedate datetime: The date/time when the item was marked as done, null otherwise\n\t@createdate datetime: The date the item was entered into the system\n\t@redirect string: Redirect to this URL after Save\t\t\t\t\n\n\t|id int64: The ID of the saved Todo item\n\t|description string: The textual description of the item\n\t|donedate datetime: The date/time when the item was marked as done, null otherwise\n\t|createdate datetime: The date the item was entered into the system\n\n#Delete: Marks a specific Todo Item as deleted\n\n\t{../controllers/todo:Remove}\n\n\t:id int64 required: The ID of the item entry to remove\n\n\t|affectedRows: int32: The number of records effected by the removal\n\n```\n\n## Websockets\n\nRestlang also supports websocket receiver and emitter definitions.  Here is an example of a chat websocket API:\n\n```\n\u003echat\n\tThis websocket method accepts a chat message from the client.\n\n\t@message string:The text that holds the chat message\n\n\u003cchat\n\tThis websocket method broadcasts a chat message to the client.\n\n\t|message string:The text that holds the chat message\n```\n\n## Documentation\n\nWriting restlang is easy, but it assumes you have at least a basic understanding of REST APIs and HTTP.  It is meant to be somewhat forgiving and flexible, and geared towards readability and documentation.\n\nRestlang works by allowing you to declare resources, methods, request parameters, and response output in a human-readable format.  Restlang does not compile to machine language or bytecode - rather it is parsed into an intermediate JSON, and then the JSON can be used to generate any number of targets.\n\n### Top-down flow\n\nRestlang is parsed in a top-down flow.  When an entity is declared, it applies to the previous entity the next level up.  For example, a resource has methods, and methods have parameters.  When a method is declared, it applies to the most recently declared resource.  When a parameter is declared, it applies to the most recently declared method.\n\nRestlang is driven off newlines and symbols, with a couple keywords thrown in.  A line that begins with one of the key symbols (defined below) is treated as the specified entity.  A line that begins with anything other than a symbol is treated as textual description for the most recently defined entity.\n\n### Symbol Reference\n\nThis is the complete reference of symbols.  Any line beginning with one of these symbols is treated as specified:\n\n-\n\n#### ```/``` (slash resource)\n\nThe slash is used to define a top-level REST resource.  In our above ToDo example, the resource is defined as ```/todo```.  This means what it sounds like - that a server is expected to serve a resource via HTTP at /todo\n\n-\n\n#### ```#``` (hash method)\nDefines an HTTP Resource access method.  You can either supply a verb (GET, POST, PUT, DELETE), or one of the Restlang methods (Entry, Collection, Add, Save, Remove).  More on the Restlang specific methods will be discussed later.\n\n-\n\n#### ```.``` (dot property)\n\nThis symbol is context specific.  A dot property can only apply to a resource or method, and must be coupled with one of the following keywords:\n\n- identity\n- parent\n- authentication\n- mutable\n\n-\n\n#### ```{``` (curly controller)\n\nThe curly is used as a reference point to an external and implementation specific controller to handle the resource.  Since Restlang is only used to define the API details, it is left to the target framework or language to implement how the request is fulfilled.  This is usually only used when generating the source code files for the server implementation.\n\n_Note_: While not required, it is good format to end the line with a closing curly brace ```}```\n\n-\n\n#### ```:``` (route param)\n\nThe colon param is used as a route parameter.  For example, the ```:id int64 required``` param for the ```/todo``` GET resource, will serve a route that a client can GET at ```/todo/:id/```\n\n-\n\n#### ```?``` (query param)\n\nThe query param is used as a querystring parameter.  For example, the ```?isdone boolean``` param for the ```/todo``` GET resource, will serve a route that a client can GET at ```/todo/?isdone=true```\n\n-\n\n#### ```@``` (body param)\n\nWhen a POST or PUT is sent, the body param is sent with the body of the request.\n\n-\n\n#### ```$``` (file param)\n\nWhen a POST or PUT is sent, the file param is sent as a form attachment with the body of the request.\n\n-\n\n#### ```|``` (pipe output)\n\nPipe output denotes the outgoing response data.\n\n-\n\n#### ```\u003e``` (receiver)\n\nThe greater-than is used to define a top-level Websocket Receiver.  In our above chat example, the receiver is defined as ```\u003echat```.  This means what it sounds like - that a server is expected to receive a chat event via Websockets at \"chat\"\n\n-\n\n#### ```\u003c``` (emitter)\n\nThe less-than is used to define a top-level Websocket Emitter.  In our above chat example, the emitter is defined as ```\u003cchat```.  This means what it sounds like - that a server is expected to emit a chat event via Websockets as \"chat\"\n\n-\n\n### Parameter declarations\n\nThe route, query, body, file, and pipe parameters all have the same format:\n```\u003csymbol\u003e\u003cname\u003e \u003cdatatype\u003e [required][default \u003cvalue\u003e]```\n\nThe symbol is one of the symbols above\n\nThe datatype is one of the datatypes below\n\nThe name is a variable type format: /[a-z]\\w*/i\n\nrequired and default cannot both be declared.  required overrides default.\n\n- The ```id``` example from Todo Get:\n\n ```:id int64 required```\n\n- The ```isdone``` example from Todo Get:\n\n ```?isdone boolean```\n\n- The ```all``` example from Todo Get:\n\n ```?all boolean default false```\n\n### \n\n\n## Datatypes\n\nThe datatype system is meant to be extensible, but supports the following defaults:\n\n - binary\n - boolean\n - byte\n - datetime\n - decimal\n - double\n - single\n - float (same as double)\n - guid\n - int16\n - int32\n - int64\n - int (same as int32)\n - number (same as int32)\n - sbyte\n - string\n - text (same as string)\n - stringN (where N is any integer greater than 0.  For example ```string255```)\n - time\n - datetimeoffset\n \n### Custom datatypes\n\nIt is possible to extend the type system and define new datatypes to use in the API.\n\n_coming soon_  \n\n## Notes\n\n - [1] Edda can be found at https://github.com/binarymax/edda\n - [2] Heimdall can be found at https://github.com/binarymax/heimdall\n - [3] Bifrost can be found at https://github.com/binarymax/bifrost\n - [4] Ragnarok can be found at https://github.com/binarymax/ragnarok\n\nRestlang is released under the MIT license.\nCopyright Max Irwin, 2014\n\n##### _made with love by Max Irwin (http://binarymax.com)_","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarymax%2Frestlang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinarymax%2Frestlang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarymax%2Frestlang/lists"}