apigeelint

Static code analysis for Apigee proxy and sharedflow bundles to encourage API developers to use best practices and avoid anti-patterns.

This utility is intended to capture the best practices knowledge from across Apigee including our Global Support Center team, Customer Success, Engineering, and our product team in a tool that will help developers create more scalable, performant, and stable API bundles using the Apigee DSL.

Status

This tool is mature and stable, works with proxy and sharedflow bundles, and continues to get enhancements. There are a variety of plugins that test Bundles, Policies, ProxyEndpoints, and more.

The tool can report results out to the console, or to a file. The tool can ingest from a directory containing the proxy bundle, or from a zipped bundle.

Installation

You can install apigeellint using npm. But, there is a minimum version of npm required.

1. First verify the version of node and npm:

   npm --version
   node --version
   

   If the npm version is 10.5.0 or later, and node version is 20 or later, then proceed to step 2. Otherwise, you need to update npm and/or node.

2. Then install apigeelint:

   npm install -g apigeelint
   

Basic Usage

Help

apigeelint -h
Usage: apigeelint [options]

Options:
  -V, --version                           output the version number
  -s, --path <path>                       Path of the proxy or sharedflow to analyze (directory or zipped bundle)
  -d, --download [value]                  Download the API proxy or sharedflow to analyze. Exclusive of -s / --path. Example: org:ORG,api:PROXYNAME or org:ORG,sf:SHAREDFLOWNAME
  -f, --formatter [value]                 Specify formatters (default: json.js)
  -w, --write [value]                     file path to write results
  -e, --excluded [value]                  The comma separated list of tests to exclude (default: none)
  -x, --externalPluginsDirectory [value]  Relative or full path to an external plugins directory
  -q, --quiet                             do not emit the report to stdout. (can use --write option to write to file)
  --list                                  do not execute, instead list the available plugins and formatters
  --maxWarnings [value]                   Number of warnings to trigger nonzero exit code (default: -1)
  --complexConditionTermCount [value]     Maximum number of terms in a condition before it is considered too complex (default: 12)
  --policyCountLimit [value]              Maximum number of policies allowed before BN006 issues a warning (default: 100)
  --profile [value]                       Either apigee or apigeex (default: apigee)
  --norc                                  do not search for and use the .apigeelintrc file for settings
  --ignoreDirectives                      ignore any directives within XML files that disable warnings
  --po025-no-retry                        disables the retry logic in PO025, when eslint finds no eslint.config.js
  -h, --help                              output usage information

Example:

apigeelint -s sampleProxy/apiproxy -f table.js

Where -s points to the apiProxy source directory or bundled zip file, and -f is the output formatter desired.

Possible formatters are: "json.js" (the default), "stylish.js", "compact.js", "codeframe.js", "codeclimate.js", "html.js", "table.js", "unix.js", "visualstudio.js", "checkstyle.js", "jslint-xml.js", "junit.js" and "tap.js".

Examples

Basic usage: ingest from a directory

apigeelint -f table.js -s path/to/your/apiproxy

The path here should be a directory name, probably ending in "apiproxy". The contents of that directory should be like this:

apiproxy/
apiproxy/proxies/
apiproxy/proxies/endpoint1.xml
apiproxy/servicecallout-async-test.xml
apiproxy/resources/
apiproxy/resources/jsc/
apiproxy/resources/jsc/...
apiproxy/policies/
apiproxy/policies/RF-Unknown-Request.xml
apiproxy/policies/AM-Response.xml
apiproxy/policies/...
...

Basic usage: ingest from a zipped proxy bundle

You can export API Proxy or Sharedflow bundles from Apigee, producing a zip archive. This tool also can read and analyze these zipped bundles:

apigeelint -f table.js -s path/to/your/apiproxy.zip

The tool will unzip the bundle into a temporary directory, perform the analysis, and then remove the temporary directory.

Basic usage: downloading a proxy bundle to analyze

You can ask apigeelint to export an API Proxy or Sharedflow bundle from Apigee, and analyze the resulting zip archive. This connects to apigee.googleapis.com to perform the export, which means it will work only with Apigee X or hybrid.

# to download and then analyze a proxy bundle
apigeelint -f table.js -d org:ORG-NAME,api:name-of-your-api-proxy

# to download and then analyze a sharedflow bundle
apigeelint -f table.js -d org:ORG-NAME,sf:name-of-your-shared-flow

With this invocation, the tool will:

• obtain a token using the gcloud auth print-access-token command
• use the token to inquire the latest revision of the proxy or sharedflow
• use the token to download the bundle for the latest revision
• unzip the bundle into a temporary directory
• perform the lint analysis
• render the result
• and then remove the temporary directory

If you do not have the gcloud command line tool installed, and available on your path, this will fail.

Variations

1. To tell apigeelint to skip invocation of gcloud, specify a token you have obtained previously:

   apigeelint -f table.js -d org:ORG-NAME,api:NAME-OF-APIPROXY,token:ACCESS_TOKEN_HERE
   

   In this case, apigeelint does not try to use gcloud to obtain an access token.

2. To tell apigeelint to download a particular revision to scan, specify the rev: segment:

   apigeelint -f table.js -d org:ORG-NAME,api:NAME-OF-APIPROXY,rev:4
   

3. To combine the prior two examples, specify a token and a revision:

   apigeelint -f table.js -d org:ORG-NAME,api:NAME-OF-APIPROXY,rev:4,token:ACCESS_TOKEN_HERE
   

4. To tell apigeelint to get a token via gcloud, then download the latest revision that is deployed in a particular environment, specify the env: segment:

   apigeelint -f table.js -d org:ORG-NAME,api:NAME-OF-APIPROXY,env:stg
   

Using External Plugins

We package apigeelint with a broad set of plugins that we think will be generally valuable. For people that want to check for some case that is not covered by the bundled plugins, you can write your own plugin. Just follow the pattern as exhibited by the many plugins that are available. External Plugins must use a name that conforms to this pattern:

• a prefix of "EX".
• followed by a dash
• followed by two uppercase alphabetic characters
• followed by three decimal digits.

Example: EX-PO007

You could, for example, create your own plugin for naming conventions, and exclude the builtin plugin that enforces naming conventions (PO007) with the -e option:

To use external plugins, specify the directory that contains them, on the command line. For example, this invocation might use your own plugin, and disable the built-in naming conventions that apigeelint checks:

apigeelint -x ./externalPlugins -e PO007 -s path/to/your/apiproxy -f table.js

In the above, -x points to the directory containing externally developed plugins.

Excluding plugins

You can, of course, exclude plugins without providing a replacement implementation:

apigeelint -s path/to/your/apiproxy -f table.js -e PO007,ST003

The above would exclude the policy naming convention check (PO007), and would also not check for conditions on an ExtractVariables with a JSONPayload (ST003), if for some reason you wanted to do that.

Writing output to a file

apigeelint -s sampleProxy/apiproxy -f table.js -w existing-outputdir --quiet

The -w option can point to an existing directory, in which case the output will be emitted to a file named apigeelint.out in that directory, in whatever format you specify with -f. An existing file by that name will be overwritten. If the -w option is not a directory, it is treated as the name of a file, and output is written there.

If you do not also specify --quiet the report will go to both stdout and to the specified filesystem destination.

Selecting a profile

Apigee X/hybrid is very similar to Apigee Edge, but there are differences in the supported policy types, and some of the supported configuration options. For example, policies like GraphQL, the AssertCondition, or the Integration policy step types are available only in X/hybrid.

As a result of these differences, a proxy that is valid in Apigee Edge might not work in Apigee X, and vice versa. Apigeelint uses the --profile option to allow the user to configure which target environment is intended: Edge (--profile apigee) or X/hybrid (--profile apigeex). The default is apigee.

# lint a proxy that will be used in Apigee X/hybrid
apigeelint -f table.js --profile apigeex -s path/to/your/apiproxy

#