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:

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