GUIDE.md

Ruuter

Ruuter is a service that enables the execution of custom "DSL files"

Basics

DSL Files

DSL files are yaml files detailing a workflow/steps that are to be executed when said DSL is called through Ruuter. More details on writing DSL files in: Writing DSL files

Location of DSL files

All of Ruuters DSL files have to be contained in single folder of the service provider's choosing (by default, this is the DSL folder, but this can be configured using the config-path property)

The structure of the DSL folder itself looks something like this:

DSL
 |--POST
 |   |-- example_dsl_1.yml
 |   |-- example_dsl_2.yml
 |   |-- SUB-DIRECTORY
 |             |-- example_dsl_3.yml
 |             |-- example_dsl_4.yml
 |
 |--GET
 |   |-- example_dsl_1.yml
 |   |-- example_dsl_2.yml
 |   |-- ...

Notes:

• It is mandatory to have at least one main directory named after an appropriate HTTP method, such as GET or POST directly in the root DSL directory ( explained in Request types)
• having any level of subdirectories inside main directories is allowed
• DSL files can share name's, as long as they are in different main directories (i.e. you can have a DSL named example.yml in both GET and POST directories)
• DSL files can not share name's, when they are in the same main directory, even when on different levels (i.e. you can not have a DSL named example.yml in both POST and POST/SUB-DIRECTORY)

Calling/Querying DSL files

All of Ruuter's DSLs are exposed through the /{dsl} endpoint, where ${dsl} is the name of the DSL without its yaml extension.

Therefore to call a desired DSL, one must simply make an HTTP request to ruuter, with the desired DSLs name, e.g: www.example-ruuter.com/messages

Request types

Ruuter supports all HTTP method types - when a DSL request is made, Ruuter tries to find the queried DSL from the directory with the same name of the incoming HTTP method type. (to limit the allowed method types, see: allowedMethodTypes property)

So if a GET query is made to the DSL messages, Ruuter will try to execute messages.yml from the GET directory.

• If messages.yml exists in the GET directory, it will be executed
• If messages.yml does not exist in the GET directory, no action will be taken
• If there is a messages.yml DSL in another "main directory", for example the POST directory, but not in the GET directory, then that DSL will not be executed.

DSL query responses

A DSL query always returns a fixed response in the form of:

{
    "response": RETURN_VALUE
}

Notes:

• RETURN_VALUE is either null, if a DSL does not have a return value, or the returnable object of the DSL, if it does

Optional parameters

Any parameter where the name starts with the word optional_, can be omitted from requests. For example, post-with-optional.yml has one required parameter and one optional_ type parameter.

return:
  return: ${incoming.body.somethingRequired}${incoming.body.optional_something}

A request made to the endpoint for this file will also require somethingRequired in the body, but optional_something can be omitted, based on the name.

POST http://localhost:8080/post-with-optional
Content-Type: application/json

{
  "somethingRequired": "Important data",
  "optional_something": "This can be omitted from the request"
}

The above request will give the same result as the one below.

POST http://localhost:8080/post-with-optional
Content-Type: application/json

{
  "somethingRequired": "Important data"
}

Writing DSL files

General functionalities

• steps
• jumps
• skip
• sleep
• scripting
• Passing parameters to DSL

Step types

• return
• assign
• mock
• http-get
• http-post
• conditional-jump
• template