163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
# 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`.
|
|
|
|
`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. |