Request DSL

rede is built to work around TOML files modeling an HTTP request. This is an example of a pretty complex HTTP request following rede DSL.

[http]
method = "POST"
url = "https://www.myapi.gl/api/images"
version = "HTTP/1.1"

[metadata]
name = "Submit image"
description = "Uploads a new image"
author = "John Carmack"

[headers]
Content-Type = "multipart/form-data"
Authorization = "Bearer {{BEARER_TOKEN}}"
Accept = "application/json"

[body.form_data]
username.text = "DoomGuy"
description.text = "Just chilling killing some demons"
image.file = "~/Pictures/hell/ripping_living_heart_from_demon.png"

We could explain the request that is being represented there, but this format is so readable that there's no need.

Tables

Each table ([table]) represents a section of an HTTP request and inside each one a series of keys or tables can be defined to provided all you need to represent the HTTP call.

Some considerations applying to the whole schema:

Only http is required, all the other tables are optional.
The order is not relevant. The order used in this section is only to improve readability.
Every valid TOML declaration is supported. There's no need to use the same as the examples here.
Any multiword key supports camel_case, lowercase and kebab-case.

[http]

This table accepts three possible keys:

url, string. The only key required in the whole DSL.
method, string. If omitted it will be GET. Accepts extension methods.
version, string of type HTTP/x.y. If omitted it will default to HTTP/1.1.

[http]
url = "127.0.0.1/api"
method = "DELETE"
version = "HTTP/2.0"

[headers]

This table is free. There's no predefined keys but all values must be strings. No transformation is applied to these headers so they must follow the HTTP restrictions.

[headers]
date = "1970-01-01"
My-Own_Weird_Header = "its valid tho"

warning: some common headers like Host and Content-Type will be autogenerated by rede based on the other fields of the request. Future plans contemplate allowing the option to disable this autogeneration

[query_params]

This table is free. There's no predefined keys but the values can't be of type datetime or tables. Arrays are supported and will be sent in the request as a comma separated list of the values.

[query-params]
size = 10
genre = "scifi"
tags = [ "dystopia", "space" ]

[body]

The body is a table that can only contain a single key specifying the type of body and the respective content of the body as value. Defining more than one body type would return an error. The see all body types refer to the body page.

body.binary = "./doc/project_v2_final_final.pdf"

[body.x-www-form-urlencoded]
name = "Feldespato"
location = "unknown"

[variables]

This table is free. There's no predefined keys but the values can't be of type datetime or tables. Arrays are supported and will be sent in the request as a comma separated list of the values.

Variables serve to set a value to replace placeholders (see).

host = "192.0.0.1"
name = "Vin"

[input_params]

The input params table can have any key desired by the user, but they must be tables. These tables can be empty or can contain the following keys:

hint, string. A hint to the user when prompted to provide a value.

[input_params]
host = { hint = "The host of the API" }
id.hint = "The ID of the resource"

To know how the input parameters are used, refer to the input parameters page.

[metadata]

This table is free but the values must be one of the primitive values (string, integer, float or boolean). It allows you to add any meaningful meta information. One key is currently queried by rede but more could come in the future (for example, description):

name. If present, rede will use it to refer to the request instead of using the filename. _This works only for printing purposes, rede run still requires the filename.

Rede Documentation