User Guide

Quick start

To get started as quickly as possible i.e. to get introduced to the most useful features it provides, we recommend you to try the interactive demo mentioned in the Introduction page.

Initialize workspace

A workspace is a directory where you keep a group of files that contains information about your API queries such as API endpoints, request parameters, headers & authentication methods, configuration files etc.

The default format of these files is YAML for better readability. However JSON is also supported.

To initialize a workspace, create an empty directory and execute below command

To initialize workspace with default YAML files

recli init

To initialize workspace with other file formats

# JSON format
recli init -e json

# TOML format
recli init -e toml

NOTE: Normally it will skip a file if it already exists. However, you may use -f or --force option to overwrite all the files.

Workspace concept

How does it work

When you initialize an workspace, you may notice a set of files are auto generated. These are just basic templates to help you understand the format. There should be atmost one file for each category of information.

For example, there should be one file that contains information about all the sites along with endpoints of each site, one file to contain set of request headers, one file to store the authentication methods and credentials, one file to save information about frequently made requests i.e. combination of payloads, parameters, headers and authentication methods used, one configuration file etc.

Why have workspaces

Simply to stay origanised. Having separate directories considered as workapaces enables us to categorize API sites, endpoints, headers, authentication methods etc into several groups. When we need to define something globally, we can always define in ~/.recli/ or even /etc/recli.

By default contents defined in current workspace will override ~/.recli's and contents defined in ~/.recli will override /etc/recli's. This priority based lookup path is also editable as the paths can be defined in recli.cfg file.

As we will eventually find out, this way of organising files will allow us to have better control on our API requests.

Commands

Help menu

To get the full list of available sub-commands enter any of the following commands:

recli help

# OR

recli -h

# OR

recli --help

Help menu of a sub-command

To get the help menu of a sub-command enter any of the following commands

# Assuming "do" is the sub-command

recli help do

# OR

recli do -h

# OR

recli do --help

Interactive mode

recli also supports interactive mode for more convenience. To get into the interactive mode, just enter:

recli

When in interactive mode, you don't need to type recli anymore. You can just enter the remaining parts of the command. For example: recli help becomes help, recli init becomes init. There are some additional cool features that you can explore with help command.

For further information on interactive mode, please read cliff documentation.

Workspace management commands

recli has a set of workspace management commands such as:

# List available sites
recli list-sites

# Show details of a particular site (e.g. ghjobs)
recli show-site ghjobs

# List available endpoints
recli list-endpoints

# Show details of an endpoint (e.g. ghjobs/p)
recli show-endpoint ghjobs/p

# Similarly

# List and show authentication method(s)
recli list-auth
recli show-auth $auth_id

# List and show headers
recli list-headers
recli show-headers $headers_id

# List and show saved requests
recli list-saved
recli show-saved $request_id

All these commands can be invoked with additional parameters such as -f json to display the output as JSON formatted text.

Doing CRUD requests

recli supports full CRUD operation.

# GET request
recli get $site_id/$endpoint_id

# POST request
recli post $site_id/$endpoint_id -k "{$key1: $value1, $key2: $value2}"

# PUT request
recli put $site_id/$endpoint_id/1 -k "$key: $value"

# PATCH request
recli patch $site_id/$endpoint_id/1 -k "$key: $value"

# DELETE request
recli delete $site_id/$endpoint_id/1

NOTE: Although $site_id/$endpoint_id/1 is not defined in any file, it will take "1" as a slug and format the URL accordingly

Formatting the output

To format the output of any CRUD request, use -f or --format option

recli get $site_id/$endpoint_id -f json

# Same as

recli get $site_id/$endpoint_id --format json

Faking a request

Any API request can be faked using -F or --fake option. When faked, recli will print the information about that request instead of doing it.

Saving a request

Requests can be saved with an ID using the -s or --save_as option with an ID.

If the ID already exists, recli will update the information overriding previous values.

This feature is best used with -F i.e. --fake option to save a request for later use without doing it.

Invoking a saved request

Saved requests can be invoked any number of times using the do sub-command.

recli do $request_id

Saved requests can also be invoked with updated parameters by overriding the saved parameters using command-line arguments.

recli do $request_id -k "$key: $value" -a $updated_auth_id -H $updated_header_id

And it can be faked and saved by adding -F -s $updated_request_id arguments.

NOTE: redo is an alias to do command

Table formatted outputs

Response of GET requests can be displayed in table format by using below commands:

# Unsaved requests
recli list $site_id/$endpoint_id
recli show $site_id/$endpoint_id/1

# Saved requests
recli dolst $request_id
recli doshw $request_id -S 1
# Same as
recli redo-list $request_id
recli redo-show $request_id -S 1

This output can be further formatted to any supported representation using the -f or --format option.

NOTE: You can also use this feature for other CRUD operations by overriding the method using -m or --method option but doing so is not recommended as result's structure may vary and formatting may fail

Auto generate API documentation

API documentation can be automatically generated from workspace files. It uses Docify library to create documents.

e.g. to generate and dump documentation into a file named README, execute any of the below commands.

# To generate markdown formatted documentation
recli doc README.md

# To generate HTML (with bootstrap) formatted documentation
recli doc README.html

Defining default command-line arguments

We can define frequently used command-line arguments such as site ID, endpoint ID, headers ID, auth ID etc in recli.cfg file. When defined in this file, these defaults will override all the other values as these will be passed as command-line arguments which has the highest priority.

For example, if we define DEFAULT_SITE_ID = testing and DEFAULT_ENDPOINT_ID = t, we can use below commands:

recli get /
# Same as: recli get testing/t

recli get //1
# Same as: recli get testing/t/1

recli get /another_endpoint
# Same as: recli get testing/another_endpoint

recli get /another_endpoint/1
# Same as: recli get testing/another_endpoint/1

recli get another_site/
# Same as: recli get another_site/t

recli get another_site//1
# Same as: recli get another_site/t/1