Getting Started

Prerequisites

To get started with the command line interface, you need to have node.js installed on your system. You can check that you have node installed by running this command:

node -v

If node is not already installed on your system, you can download it from https://nodejs.org/en/download/. Minimum version that is expected to work with is 16.+.

Finally, make sure the gateway that you want to talk to is ready with Graphman internal service published.

Install the client from registry

• install the client directly from the Broadcom's npm registry
  • npm install @layer7/graphman --global --registry https://packages.broadcom.com/artifactory/api/npm/layer7-npm
• in case if you want to install the particular version of client, specify release version.
  • npm install @layer7/graphman@<some-release-version> --global --registry https://packages.broadcom.com/artifactory/api/npm/layer7-npm
• verify the installation by running the version command
  • graphman version
• choose some directory to keep the custom queries, extensions and configuration files and set the GRAPHMAN_HOME environment variable to it.
  • export GRAPHMAN_HOME=/path/to/layer7-graphman-home

Note

• As the module is installed globally, graphman client can be executed from any directory workspace.
• And, no extension is needed to refer it.

Important

• Latest release available is 2.0.9
• Please refer the Previous Releases page for installing the legacy clients

Here, you may skip to the Configure Home directory section.

Update the client from registry

• installed client (from Broadcom's registry) can be updated to the latest available.
  • npm update @layer7/graphman --global --registry https://packages.broadcom.com/artifactory/api/npm/layer7-npm
• verify the update by running the version command
  • graphman version

Note

npm-update is not applicable if the existing client was not installed from the registry. You must uninstall it and continue installing it from registry.

Uninstall the client

• starting from 1.3.* releases, client should be uninstalled using npm.
  • npm uninstall @layer7/graphman --global
• in particular to the 1.3.00 release, cd to the home directory and run the npm-uninstall command.
  • npm uninstall @layer7/graphman
• remove the client's home directory path from the PATH environment variable
• delete the client's home directory itself

Configure home directory

Run the following command to quickly setup the home directory for use

graphman config --init-home /path/to/layer7-graphman-home

And, set the GRAPHMAN_HOME environment variable to your home directory if not done already.

The graphman.configuration file from the home directory can be used to configure the client for effective use. You may add one or more gateway profiles (under gateways section) to it and refer them by name using --gateway parameter at CLI. When this parameter is omitted, it will be defaulted to the default gateway profile.

{
    "gateways": {
        "default": {
            "address": "https://localhost:8443/graphman",
            "username": "admin",
            "password": "7layer",
            "rejectUnauthorized": false,
            "keyFilename": null,  /* key for mTLS based authentication */
            "certFilename": null,  /* cert for mTLS based authentication */
            "passphrase": "7layer",
            "allowMutations": false  /* true to allow mutations */
        }
    },

    "options": {
        "log": "info",
        "policyCodeFormat": "xml",
        "keyFormat": "p12"
    }
}

Note

mTLS based authentication takes the precedence over the password-based authentication.

Note

In order to protect the gateways from the accidental mutations, by default, mutation based queries are disallowed. You must enable them by setting the allowMutations field of the gateway profile to true. It is recommended to set this value to false in the profile, and override it from the CLI arguments (--gateways.<profile>.allowMutations).

Now, you are ready to start using it.

To bundle the entire configuration of the gateway, run the following command:

graphman export --gateway <source-gateway> --using all --output source-bundle.json

You can apply this configuration bundle as-is to the target gateway.

graphman import --gateway <target-gateway> --input source-bundle.json

Congratulations, you just packaged all the configuration from the source gateway, and applied it to the target gateway.

Run it with no arguments will reveal the supported operations. You can get more information about every operation by specifying the --help parameter.

graphman <operation> --help

Warning

Graphman is still under continuous development to extend its support to the gateway entities. As GraphQL schema is subjected to the frequent modifications, new or modified queries may not be compatible with the older gateways.

Supported schema(s) (i.e., version of the Layer7 API Gateway) can be observed from compatibility-matrix.

You can switch to the one of the supported schemas either by specifying in the graphman.configuration file or using CLI argument (--options.schema <schema>)