restemplate/README.md

# restemplate

restemplate is a simple tool I wrote, to simplify queries against REST services.
Usually I used curl together with a lot of text files containing the requests I send and manually replaced the necessary content within the URL and the payload.

To ease this, I wrote restemplate.

## Features

* Supports all HTTP methods
* Simple templates/profiles specifying how a call looks like
* Variable replacement in Headers, URIs and the Payload
* Query users for variables
* Store "last" variable values to be easily reused
* SSL support via openssl
    - dynamically loads openssl, so if you don't use it, you don't need it
* Entirely written in FreePascal
    - ... it is therefore cross-platform (compilable :-))

## Usage

Calling restemplate is as easy as calling `restemplate [options] <template>`.

`[options]` may be:

`-h` or `--help`
:   Shows a help screen with all available options.

`-l` or `--list`
:   Lists all global templates

`<template>` is either a filename or a global template (more on that later).

## Example

Let's start with a simple example, and explain the seen features later.

```
Ask username
Ask key
Ask value
Header X-UserName: @username
Method POST
Call http://localhost/myservice/keys/@key

{
    "value": "@value"
}
```

Executing this profile will result in:

```
$ restemplate example.rest
username: myuser
key: somekey
value: foobar
Calling http://localhost/myservice/keys/somekey

Status: 200 (OK)

Headers:
  Content-Type: application/json

{"statusCode": 0}
```

## Fileformat

The profiles are simple text files, parsed line by line.
The parser starts in command mode. Each line has to start with a valid command.
Empty lines or lines starting with "#" are ignored (which can be used to make profiles more readable and comment out commands without deleting them).

Once the first none-empty line is unrecognized (no command found), the parser will treat the remaining part of the profile as payload to be sent within the request.

### Commands

`Ask <variablename>`
:   Prompts the user for the input of `<variablename>`. If the value has been given in a previous run, it is suggested as default value so the user can simply accept the "last" value. This eases re-runs of the same profile with only minor (or no) changes.
    This can be repeated multiple times.

`Ask#<variablename>`
:   Prompts the user for the hidden input of `<variablename>`. This can be used to input passwords. These values are not persisted and therefore no default values are suggested.
    This can be repeated multiple times.

`Header <http header>`
:   Sets the given http header for the request.
    This can be repeated multiple times.
    Variables in the form of `@<variablename>` are replaced accordingly.

`BasicAuth <username> <password>`
:   Sets the necessary header for basic authentication. The first char after `BasicAuth` (usually a space) is treated as separator for `<username>` and `<password>`. So in case the username itself contains a space, you can safely use a different char here. Example: `BasicAuth#Complicated Username With Spaces#andsomepassword`

`Highlight <RegEx> [FG<color>] [BG<color>]`
:   Highlights the matching parts with the given foreground or background color as specified using colors codes.

`Method <HTTP Method>`
:   This sets the method to be used for the call.

`FormField <key>=<value>`
:   Adds a key/value pair to the url-encoded-form-data body.
    The encoding will be done automatically!
    This can be repeated multiple times but will only be used when Method == POST.
    The Content-Type header is set automatically too.

`Compress[ed]`
:   Adds support for gzip,deflate compression to the connection.

`Proxy <server> <port>`
:   Enables HTTP proxy support.

`ProxyAuth <username> <password>`
:   Sets authentication for the HTTP proxy.
    Same syntax as `BasicAuth`.

`Generate <variablename> <generator>`
:   Sets a variable with a generated value.
    Possible generators:
    * `UUID`
    * `unixtime` (a unix timestamp)
    * `localtime` (a formatted time)
    * `isodatetime` (Date and Time according to ISO8601)
    * `isodate` (Date according to ISO8601)
    * `isotime` (Time according to ISO8601)

`Expect <expectation type>=<expecation>`
:   Checks expectations after the request.
    * `Status=<statuscode>`: checks, if the status code matches
    If an expectation fails, the application exists with code 5.

`Call <URL>`
:   This prepares the actual call by providing the URL to be called.
    Variables in the form of `@<variablename>` are replaced accordingly.

## Profiles

Having a profile in a local file can be inconvenient if you have restemplate in the `$PATH` for example and want to call it from "anywhere".
Therefore you can save profiles in `~/.config/restemplate/templates/*.rest`. The filename of these files (sans `.rest`) will be used as profile name and listed as well as recognized by restemplate.

## Compiling

You need at least FreePascal 3.0 and it is recommended to use Lazarus as IDE.

Compiling from commandline is as easy as: `fpc -XX -CX -Xs -Fujtemplate restemplate.pas`

If you use Lazarus, you can simply open the project file `restemplate.pas`.

# Appendix A: Color Codes

Taken from the FPC source:


```Pascal
{ Foreground and background color constants }
  Black         = 0;
  Blue          = 1;
  Green         = 2;
  Cyan          = 3;
  Red           = 4;
  Magenta       = 5;
  Brown         = 6;
  LightGray     = 7;

{ Foreground color constants }
  DarkGray      = 8;
  LightBlue     = 9;
  LightGreen    = 10;
  LightCyan     = 11;
  LightRed      = 12;
  LightMagenta  = 13;
  Yellow        = 14;
  White         = 15;

{ Add-in for blinking }
  Blink         = 128; 
```

Blink can be added by setting the appropriate bit.