LRestClient

Command-line, json-based REST-Client written in Typescript.

• Usage
• Definitions
• Commands
• Project Structure
• All commands (generated)

Usage

$ npm install -g lrclient
$ lrc COMMAND
running command...
$ lrc send ./endpoints/accounts/user/profile.json -v "user: lmnch"
Requesting...
 GET http://www.github.com/lmnch/LRClient
Authorization: Bearer ...
User-Agent: Mozilla Firefox
...

Definitions

Variables

Variables can be used to parameterize your requests. The value of a variable can be references like this:

{{variablename}}

The value of a variable can be defined on different levels which overwrite each other in the following order (lower index overwrites higher index):

1. Local variables: These are variables that are passed directly at the call and might be used e.g. for dynamic values which are returned by another request
2. Endpoint variables: Defined at the endpoint which should be called
3. Environment variables: Defined for the currently selected environment

Variable values can contain other variables (but please do not create circular dependencies):

{
  "variables": {
    "username": "bernd",
    "authorization": "{{username}}:{{password}}",
    "password": "bernd!rocks"
  }
}

(the variable authorization will be resolved to bernd:bernd!rocks)

Headers

There's a similar hierarchy like for variables:

1. Endpoint headers
2. Environment headers

Variables can be used inside of the value of a header:

{
  "headers": {
    "Authorization": "{{authorization}}"
  },
  "variables": {
    "username": "bernd",
    "authorization": "{{username}}:{{password}}",
    "password": "bernd!rocks"
  }
}

Payloads

A payload can be used by creating a json file of this form:

{
    "payloadType": "application/json",
    "data": "{\"street\":\"Teststreet\",\"name\": \"{{user}}\"}"
}

Inside of this data field, variables can be resolved. Currently, there are three types of payloads supported:

• JSON: data contains the whole JSON string
• Text: data contains the whole text
• Files: data contains the path to the file that should be uploaded

The payload which should be used for a request can be defined on two levels (similar to variables):

1. "Locally": Directly at the call via parameter
2. Endpoint: Default payload for the endpoint

The payload can be selected by refering it in the send command call lrc send ENDPOINT.

Endpoint

The job of a REST-Client is obvoiusly to call REST-Endpoints. Such an endpoint is defined as following:

{
  "url": "http://localhost:8080/api/upload",
  "method": "POST",
  "headers": {
    "User-Agent": "Mozilla Firefox"
  },
  "variables": {
    "user": "lmnch"
  }
}

It consists of the mandatory fields: url (of course), the HTTP method that should be used and the resultType. Additionally, variables and headers can be defined optionally here. It is also possible to overwrite/supplement the headers and variables defined in the environment.

The endpoint file that should be used can be selected by its path when using the send command.

Environments

The LRClient can be configured by using different environments. An environment contains headers and custom variables which are applied to all request executed with the enviroment.

{
  "headers": {
    "Authorization": "Bearer {{bearerToken}}",
    "User-Agent": "Mozilla Firefox"
  },
  "variables": {
    "bearerToken": "...",
    "baseUrl": "http://www.github.com",
    "user": "lmnch",
    "repository": "LRClient",
    "requestUrl": "{{baseUrl}}/{{user}}/{{repository}}"
  }
}

Currently, the environment has to be defined directly in a JSON file. But, one can switch between different files with the lrc env set command.

Implementation

Internally, the imported script is wrapped in a async function with lrc and log as parameters. These values are passed to the context of the execution. So internally, the example from before results in the following snippet:

const executionLrcMethod = async (lrc) => { 

  let password = "test";

  // Creates a new user
  const createdUser = await lrc.send("./endpoints/create-new-user.json", { name: "lukas", password: password });

  // Update the user's password 10 times
  for(let i = 0; i < 10; i++){
    let newPassword = password;
    await lrc.send("./endpoints/update-password.json", {name: "lukas", oldPassword: password, newPassword: newPassword});
    password = newPassword;
  }

};
executionLrcMethod(lrc, log);

This allows the usage of the await keyword in the script files.

Logging

For all the request sending commands (lrc send ENDPOINT and lrc script execute SCRIPTFILE), the default logging behaviour can be overwritten by using the loggedFields flag (or the alias -l). Multiple values can be passed using this flag:

• env: Logs the current environment before executing the request (this contains headers and variables)
• endpoint: Logs the endpoint definition which was selected (contains basic information like url but also variables and headers)
• endpoint_payload: Logs the payload which is linked in the endpoint
• req: Logs the resulting request after variable resolution
• req_body: Logs the resulting body after variable replacement
• resp: Logs information about the response like status code
• resp_body: Logs the extracted body of the response

The lrc send ENDPOINT command uses per default the logging flags req, req_body, resp, and resp_body. The lrc script execute SCRIPTFILE) command (logging flags apply to all requests made by the script) logs per default nothing. Setting one of the flags as parameter in the cli overwrites the default behaviour what means the default flags won't be logged (if they are not specified again manually).

Project structure

The entrypoint are the classes in the src/boundary directory.

It contains the LRClient which performs the REST calls and the ConfigManager which allows to load and change the configuration. src/model contains the data classes that define how the requests are performed. This contains some enums (HttpMethod, PayloadType) and classes that contain the definition (Environment, Endpoint). Further, theres a special directory payload for different payload types. They use classes from the src/variables directory which manage the variables and variable replacement.

The LRCLogger (src/logging/LRCLogger) is used to print the model classes to the console in a colorful way.