RESTish Integration

The auth-cli can integrate with another cli tool called Restish. Restish is a general purpose tool for issuing rest-based api calls from the command line and it can be useed to call auth api endpoints.

The auth-cli restish command acts as a passthrough to restish, that uses your existing auth-cli access_token and environment for example the following two commands are equivalent. By calling restish through auth-cli the a-ci enviroment variable wasn’t needed:

npm run test

restish a-ci tenant-client-controller-find 1

auth-cli restish tenant-client-controller 1 (

To setup and use Restish please refer to the Restish Notes

Restish Notes:

Restish on Github

Install Restish

On Mac you can use Homebrew

Add the tap

brew tap danielgtaylor/restish

Install the executable

brew install restish

A .restish folder is created in your <HOME> directory

The api endpoint can be found at either a url or a local file path.

Auth OpenApi URL

To reference and use a local copy, copy the openaip.json to <HOME>/.restish/ls-openapi.json

Create a local environment config file

The path of the configuration file is _/.restish/apis.json_

Multiple environments can be described in this file.

Configuration files can also be created from the command line ex:

restish api configure stage

would create a configuration create a config for a ‘stage’ environment

Here is a apis.json Config file for local and a-ci environments:

The spec_file setting in apis.json is the location of the open json file.

{
  "local": {
    "base": "http://localhost:7000/_api",
    "spec_files": ["/Users/someuser/ls-openapi.json"],
    "profiles": {
      "default": {
        "auth": {
          "name": "oauth-authorization-code",
          "params": {
            "audience": "http://localhost:7000/_api/auth/ls",
            "authorize_url": "http://localhost:7000/_api/auth/ls/authorize",
            "client_id": "auth-ui",
            "scopes": "openid profile email",
            "token_url": "http://localhost:7000/_api/auth/ls/oidc/token"
          }
        }
      }
    }
  },
  "a-ci": {
    "base": "https://a-ci.labshare.org/_api",
    "spec_files": ["https://a-ci.labshare.org/_api/auth/explorer/openapi.json"],
    "profiles": {
      "default": {
        "auth": {
          "name": "oauth-authorization-code",
          "params": {
            "audience": "https://a-ci.labshare.org/_api/auth/ls",
            "authorize_url": "https://a-ci.labshare.org/_api/auth/ls/authorize",
            "client_id": "auth-ui",
            "scopes": "openid profile email",
            "token_url": "https://a-ci.labshare.org/_api/auth/ls/oidc/token"
          }
        }
      }
    }
  }
}

Creating endpoint aliases

The OpenAPI specification allows for alias names for api endpoints. These alias names can be set up in auth by adding the alias to the decorator of the controller method. Then, when the api json is generated the aliases will be available.

decorators in loopback

Restish Aliases

ex in user.controller.ts in auth:

  @get('/auth/admin/tenants/{tenantId}/users', {
    'x-cli-aliases': "users-list",
    responses: {
      200: {
        description: 'Array of Users model instances',
        ...
  })

The alias will now be in the openapi.json

    "get": {
        "x-controller-name": "UserController",
        "x-operation-name": "find",
        "tags": [
            "Users"
        ],
        "x-cli-aliases": [
          "users-list"
        ],
        
        ...

Creating a shell alias

Restish wants to be called from the ~/.restish directory. In order to avoid the need to cd to this directory, it is convient to create an alias. This can be done in your ~/.zshrc file if you are using zsh or in ~/.bashrc if you are using a bash shell.

in your file, add the following function and alias:

restish_call () {
  pushd ~/.restish; restish $@; popd
}

alias restish="restish_call"

Restish auth-cli integration

The auth-cli api-method is a pass through to restish that sets the environment and can use the auth-cli access-token. ex restish a-ci users-list 1 is equivalent to auth-cli restish users-list 1 when working in tha a-ci environment

Examples

Get a list of api endpoints

restish a-ci list

List all users in a-ci for tenant 1 using the http verb and the url (leaving off the base url)

restish a-ci get auth/admin/tenants/1/users

List all users in a-ci for tenant 1 using the endpoint name - user-controller-find

restish a-ci user-controller-find 1

List all users in a-ci for tenant 1 using the alias name

restish a-ci users-list 1

List all users in a-ci for tenant 1 and only display the username and email

restish a-ci user-controller-find 1 -f "body[].{username,email}"

List all users in a-ci output as yml

restish a-ci user-controller-find 1 -o yml

Get help on a command ex the send email command

restish a-ci email-controller-send-email --help

Post data by piping json into the command ex to send an email

echo '{"from":"kp1@email.com", "to":["kp2@email.org"], "subject":"Restish is Great", "html":"Wow"}' | restish a-ci email-controller-send-email 1`

Post data entire with single quotes around entire post body and using restish shorthand syntax (use this when there is an array in the post data)

restish a-ci email-controller-send-email 1 'from: me@gmail.com, subject: Restish is Great, html: Wow, to[]: you@labshare.org'

Post data by using the restish shorthand syntax and individualy quoted fields

restish a-ci user-controller-create-user 1 username:'jtest', email:'jtest@test.com', familyName:'test', givenName:'joe'

Filter data using JMES path sytnatx

restish a-ci user-controller-find 1 -f "body[?username=='jtest'].{username,email}"

CLI RESTish Integration