Workspace Files Explained

All the files that may reside in a workspace or ~/.recli or /etc/recli are explained here.

By default recli searches for each file in following order: . > ~/.recli > /etc/recli and reads whatever it finds first.

1. Configuration file

This file has a fixed name: recli.cfg, a fixed lookup path . > ~/.recli > /etc/recli and a fixed syntax as it is the first file recli reads when a command is invoked.

All the variable parts of configuration used by recli such as default file extension, lookup path etc. may be defined in this file.

This file looks like this:

### Configuration file for RESTEasyCLI
### Values mentioned here are default values
### Uncomment lines and edit values as required

### Request methods to allow (e.g. GET, POST, PUT, PATCH, DELETE)
DEFAULT_ALLOWED_METHODS = GET, POST, PUT, PATCH, DELETE

### Where to search for workspace files (priority highest -> lowest)
SEARCH_PATHS = ., ~/.recli, /etc/recli

### Which file format to use for initializing workspace files (e.g. v0.1, v1.0)
DEFAULT_FILE_FORMAT = v1.0

### Which file extension to use for initializing workspace files (e.g. json, yaml, yml)
DEFAULT_FILE_EXTENSION = yaml

### Name of the sites template file
SITES_TEMPLATE_FILENAME = sites

### Name of the auth template file
AUTH_TEMPLATE_FILENAME = auth

### Name of the headers template file
HEADERS_TEMPLATE_FILENAME = headers

### Name of the saved requests template file
SAVED_REQUESTS_TEMPLATE_FILENAME = saved

### Default output format (e.g. json, yaml)
DEFAULT_OUTPUT_FORMAT = yaml

### Title for current workspace
WORKSPACE_TITLE = RESTEasyCLI

### Description for current workspace
WORKSPACE_DESCRIPTION =

### Default values to provide when no command-line argument is provided
DEFAULT_SITE_ID =
DEFAULT_ENDPOINT_ID =
DEFAULT_HEADERS_ID =
DEFAULT_AUTH_ID =
DEFAULT_TIMEOUT =
DEFAULT_CERTFILE = 

As shown above, this is a flat file with key-value pairs separated with =. Any of the characters # or ; can be used to put comments.

NOTE: Do not use single or double quotes to define values and use # or ; only at the starting of a line

2. Sites file

This file holds information about different sites, endpoints exposed by each site, default authentication used, default headers used etc. This file in YAML format looks like this:

Minimal parameters

version: v1.0
sites:
  $site_id:
    base_url: $base_url
    endpoints:
      $endpoint_id:
        route: $endpoint_path

All available options

version: v1.0
sites:
  $site_id:
    base_url: $base_url
    headers: $headers_id
    auth: $auth_id
    verify: $verify
    timeout: $timeout
    methods:
    - $allowed_method1
    - $allowed_method2
    endpoints:
      $endpoint_id:
        route: $endpoint_path
        headers: $headers_id
        auth: $auth_id
        verify: $verify
        timeout: $timeout
        methods:
        - $allowed_method1
        - $allowed_method2

Both versions of sites file defines an endpoint $base_url/$endpoint_path. One with minimal parameters, another with all the available options.

All the undefined fields will inherit values from parent if available or take default values.

Name of this file can be changed by modifying SITES_TEMPLATE_FILENAME field in configuration file.

3. Headers file

This file holds key-value pairs to be sent as request headers.

Two actions are supported: only and update. only will remove previously applied headers by parents and apply new set of key-value pairs. update only adds new key-value pairs or updates existing ones without removing any. This file in YAML format looks like this:

version: v1.0
headers:
  $header_id:
    action: $action
    values:
      $key1: $value1
      $key2: $value2

Name of this file can be changed by modifying HEADERS_TEMPLATE_FILENAME field in configuration file.

4. Auth file

This file stores authentication methods. Key-value pairs may vary based on authentication type. This file in YAML format looks like this:

Basic auth

version: v1.0
auth:
  $auth_id:
    type: basic
    credentials:
      username: $username
      password: $password

Token auth

version: v1.0
auth:
  $auth_id:
    type: token
    credentials:
      token_type: $token_type
      token_hash: $token_hash

Name of this file can be changed by modifying AUTH_TEMPLATE_FILENAME field in configuration file.

5. Saved requests file

This file stores information of all the requests saved for re-use purpose. Along with manual updates, this file also gets updated automatically by recli when we use -s or --save option to save a request. This file in YAML format looks like this:

Minimal parameters

version: v1.0
saved_requests:
  $request_id:
    method: $method
    site: $site_id
    endpoint: $endpoint_id

All available options

version: v1.0
saved_requests:
  $request_id:
    method: $method
    site: $site_id
    endpoint: $endpoint_id
    slug: $slug
    headers: $headers_id
    auth: $auth_id
    verify: $verify
    timeout: $timeout
    kwargs:
      $key1: $value1
      $key2: $value2

A request inherits undefined values from it's endpoint which already inherited it's undefined values from it's site.

Name of this file can be changed by modifying SAVED_REQUESTS_TEMPLATE_FILENAME field in configuration file.

To understand what the fields kwargs, verify etc. mean, check the next section Fields Explained.

NOTE: All workspace files except the configuration file contain a version information to allow extension of currently defined format tackling incompatibility