https://github.com/binarymax/restlang

A Web API description language
https://github.com/binarymax/restlang

Last synced: 6 months ago
JSON representation

A Web API description language

Host: GitHub
URL: https://github.com/binarymax/restlang
Owner: binarymax
License: mit
Created: 2014-05-03T20:46:53.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2014-07-19T18:31:42.000Z (over 11 years ago)
Last Synced: 2024-08-10T20:33:01.312Z (over 1 year ago)
Language: JavaScript
Homepage: http://binarymax.com/restlang/
Size: 504 KB
Stars: 8
Watchers: 3
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

A cross-compiling DSL (domain specific language) for building APIs

## Hello World

```restlang
/helloworld

This API returns a 'Hello World' message!

#Get

{/controllers/helloworld.Get}

|message string: The text that holds the message

```

## Introduction

Restlang is a markdown-inspired language that is used to generate server route specifications, client libraries, testing scripts, and developer documentation for web based APIs.

Restlang defines the 'What' and not the 'How' of APIs.

For example, you can easily define a Todo list API resource with 50 lines of restlang, and then automatically generate all of the following:
- The API routes for Node/Express
- A jQuery AJAX library to consume the above API
- Integration test scrips for mocha
- Static HTML documentation files

The 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.

As of writing, only one parser exists and is in development. This repository holds the restlang.js parser for Node and JavaScript.

## Installation

```
npm install restlang
```

Restlang 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.

### Targets

A Target is an end result output of the Restlang parser coupled with a generator. Currently only one target generator is supported through Edda [1].

#### _Framework targets_

Currently, only node is supported as a target through Heimdall[2]. Though Heimdall is semi-mature and in production use, support for Restlang->Heimdall is experimental.

Future server framework targets in planning are:
- Golang
- PHP
- Openresty
- MVC.NET

#### _Client targets_

A 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.

Future client targets in planning are:
- iOs
- Android
- jQuery
- Node
- Golang
- .NET

#### _Testing targets_

Automation of Integration Testing is a key goal of Restlang. Currently only node/mocha is being developed. See Ragnarok for more information [4].

Aside from Ragnarok there are no other Testing targets planned.

#### _Documentation for Humans target_

Though mostly human readable in its raw form (again like markdown), a developer documentation target is in the works to generate static documentation HTML.

## Todo Example

Here is an example of a Todo list API in Restlang:

```restlang
/todo: A Todo list CRUD API

.identity id int64

#Get: Gets a specific To-Do Item

{../controllers/todo:Entry}

:id int64 required: The ID of the item entry to retrieve

|id int64: The ID of the item
|description string: The textual description of the item
|donedate datetime: The date/time when the item was marked as done, null otherwise
|createdate datetime: The date the item was entered into the system
|isdeleted boolean: True if the item has been removed from the list

#Get: Gets a list of Todo Items for a List

{../controllers/todo:Collection}

?isdone boolean: If true, only return done items, if false only return not done items
?all boolean default false: if true, return all items, done or not

#Post: Adds a new Todo Item to a List

{../controllers/todo:Add}

@description string required: The textual description of the item
@donedate datetime: The date/time when the item was marked as done, null otherwise
@createdate datetime: The date the item was entered into the system
@redirect string: Redirect to this URL after Add

|id int64: The ID of the newly added item
|description string: The textual description of the item
|donedate datetime: The date/time when the item was marked as done, null otherwise
|createdate datetime: The date the item was entered into the system

#Put: Saves a specific Todo Item

{../controllers/todo:Save}

:id int64 required: The ID of the item entry to save

@description string: The textual description of the item
@donedate datetime: The date/time when the item was marked as done, null otherwise
@createdate datetime: The date the item was entered into the system
@redirect string: Redirect to this URL after Save

|id int64: The ID of the saved Todo item
|description string: The textual description of the item
|donedate datetime: The date/time when the item was marked as done, null otherwise
|createdate datetime: The date the item was entered into the system

#Delete: Marks a specific Todo Item as deleted

{../controllers/todo:Remove}

:id int64 required: The ID of the item entry to remove

|affectedRows: int32: The number of records effected by the removal

```

## Websockets

Restlang also supports websocket receiver and emitter definitions. Here is an example of a chat websocket API:

```
>chat
This websocket method accepts a chat message from the client.

@message string:The text that holds the chat message

``` (receiver)

The greater-than is used to define a top-level Websocket Receiver. In our above chat example, the receiver is defined as ```>chat```. This means what it sounds like - that a server is expected to receive a chat event via Websockets at "chat"

#### ```<``` (emitter)

The less-than is used to define a top-level Websocket Emitter. In our above chat example, the emitter is defined as ``` [required][default ]```

The symbol is one of the symbols above

The datatype is one of the datatypes below

The name is a variable type format: /[a-z]\w*/i

required and default cannot both be declared. required overrides default.

- The ```id``` example from Todo Get:

```:id int64 required```

- The ```isdone``` example from Todo Get:

```?isdone boolean```

- The ```all``` example from Todo Get:

```?all boolean default false```

###

## Datatypes

The datatype system is meant to be extensible, but supports the following defaults:

- binary
- boolean
- byte
- datetime
- decimal
- double
- single
- float (same as double)
- guid
- int16
- int32
- int64
- int (same as int32)
- number (same as int32)
- sbyte
- string
- text (same as string)
- stringN (where N is any integer greater than 0. For example ```string255```)
- time
- datetimeoffset

### Custom datatypes

It is possible to extend the type system and define new datatypes to use in the API.

_coming soon_

## Notes

- [1] Edda can be found at https://github.com/binarymax/edda
- [2] Heimdall can be found at https://github.com/binarymax/heimdall
- [3] Bifrost can be found at https://github.com/binarymax/bifrost
- [4] Ragnarok can be found at https://github.com/binarymax/ragnarok

##### _made with love by Max Irwin (http://binarymax.com)_

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/binarymax/restlang

Awesome Lists containing this project

README