Table of Contents generated with DocToc
- Why do we need a tool to manage the API Development Lifecycle for Apigee?
- Getting Started
- Steps to get started (deprecated)
- Supported tasks
- Most Important Tasks
- Test what you just deployed
- Use apigee gateway and with Yahoo Weather standard Target
- Use apigee gateway calling Yahoo Weather through Apigee Node.js as Target
- Use apigee gateway retrieving static content through Node.js as Target
- Use apigee gateway retrieving static content through Node.js as Target (nested folder)
- Use apigee gateway leveraging a JavaCallout policy
- Complementary Tasks
- Node.js Deployment
- JavaCallout Policy Support
- Search and Replace Functionality
- Continuous Integration with Jenkins
- API Static Code Analysis
- Reusability of code with Maven Plugins and shell scripts/command line tools
- Contributing
- Pluggable environment (thousands of npm and grunt modules and plugins)
- Grunt is perfect for applying continuous improvement by easily adding custom tasks. See Tasks directory
- It's pure JavaScript running on Node.js. Enough said, right :-)
- Deploys Node.js API Proxies (node_modules, resources, and public directories) see Gruntfile.js compress task. Also support of Apigee NPM API
- Supports JavaCallout Policies. Compiles, package and include Java library dependencies.
- It's ready for TDD with Mocha.js and Chai. See tests directory.
- Does static code analysis with JSHint and ESLint. So, out-of-the-box, you get the ability to add custom rules that promote coding best practices in JavaScript. See ESLint custom rules
- Reviews JavaScript file complexity by leveraging Grunt-Complexity
- Suppports Apigee KVM migration see Gruntfile.js for configuration task or please visit grunt-apigee-kvm
- It's easier to troubleshoot. cURL command support. Just pass
--curl=true - Searches and replace files content with RegEx, string patterns, or XPath. See string-replace and xmlpoke tasks in Gruntfile.js
- Includes files dynamically from common git submodule to promote DRY (Don't Repeat Yourself) principle (check search-and-replace.js entries)
- It's compatible with most CI tools Jenkins, Bamboo, Go, and Travis
- Sends automatic desktop notifications with Grunt Notify
- It's compatible with IDEs. See Chrome Grunt Dev Tools and Grunt Task Runner for Web Storm
- It's Compatible with Maven. So you can still run JMeter tests or single Maven tasks, if Mocha doesn't suit you needs, see shell:run_jmeter_tests target. tools examples.
The easiest way to use this plugin is by leveraging Yeoman. Follow Getting Started from Apigee API Proxy Generator.
Getting started with Yeoman is much easier than following steps above. You no longer need to folow these steps unless you want learn how to use Git Submodules.
Prerequisites: Node.js and NPM
Optional tools: Git. You can still use this plugin without Git, however manual steps will be required to initialize common folder.
- Step 1: Clone this repo with Git.
git clone https://github.com/apigeecs/apigee-deploy-grunt-plugin.gitIf you don't have Git is installed, download this repo as a zip file and expand it somewhere in the filesytem. - Step 2:
cd apigee-deploy-grunt-plugin - Step 3: open apigee-deploy-grunt-plugin folder and execute the two commands:
git submodule init
git submodule update
These two commands initialize Git Submodules by downloading source to Common folder from common branch. Installation without Git requires to download common branch as a zip file and expand its content into common folder (common/apiproxy)
- Step 4: setup Apigee Edge credentials as system environment variables ae_username and ae_password or just pass credentials as arguments
- Step 5: install grunt cli
sudo npm install grunt-cli -g - Step 6: execute
npm installto install all grunt dependencies - Step 7: Edit and add environment to grunt/apigee-config.js file. Each environment will be referenced below as a flag e.g. --env={test, prod}
- Step 8: Edit and add environments to grunt/search-and-replace-files.js for string replacements.
- Step 9: run
grunt --env=test --username={apigee_edge_email_address} --password={apigee_edge_password} --debug
One of the cool features of Apigee is seamless deployment or zero downtime. By default Grunt deploys in that mode. The following command will deploy api bundles with that mode:
$ grunt --env=test --username={apigee_edge_email_address} --password={apigee_edge_password} --debug --curl=trueNote: Pass --debug flag to display Management API responses.
The following command will undeploy is similar to the default task, however it undeploys the bundle, so there's some downtime. import, and deploy the api bundle:
$ grunt IMPORT_DEPLOY_BUMP_REVISION --env=test --username={apigee_edge_email_address} --password={apigee_edge_password} --debug --curl=trueThe following command will update current revision. Please be aware that it undeploys the current revision, so task is more suitable for development to avoid creating new revisions:
$ grunt UPDATE_CURRENT_REVISION --env=test --username={apigee_edge_email_address} --password={apigee_edge_password} --debug --curl=trueOnce previous is executed, you should be able to try the following calls:
https://{org-env}.apigee.net/{api-basepath}/apigee/forecastrss?w=2502265
Example https://testmyapi-test.apigee.net/weathergrunt/apigee/forecastrss?w=2502265
https://{org-env}.apigee.net/{api-basepath}/forecastweather_node/2502265
Example https://testmyapi-test.apigee.net/weathergrunt/forecastweather_node/2502265
https://{org-env}.apigee.net/{api-basepath}/images/tree.jpg
Example https://testmyapi-test.apigee.net/weathergrunt/images/tree.jpg
https://{org-env}.apigee.net/{api-basepath}/tree.jpg
Example https://testmyapi-test.apigee.net/weathergrunt/tree.jpg
Disabled by default. Read section below for enabling directions.
https://{org-env}.apigee.net/{api-basepath}/javacallout
Example curl https://testmyapi-test.apigee.net/weathergrunt/javacallout
grunt getDeployedApiRevisions --env=test --debug
grunt undeployApiRevision:{revision_id} --env=test --debug
grunt deployApiRevision:{revision_id} --env=test --debug
grunt getAllApiRevisions --env=test --debug
grunt importApiBundle --env=test --debug --debug
grunt deleteApiRevision:{revision_id} --env=test --debug
$ grunt updateApiRevision:{revision_id} --env=test
See grunt/apigee-config.js file.
grunt compress --env=test
grunt clean --env=test
grunt --help or grunt availabletasks --env=test will display a nicer colored output.
--username={apigee_edge_username}
--password={apigee_edge_password}
--skip-tests=true
--curl generate curl commands to be executed from command line
--override
--delay={seconds}
Upload node.js modules (by default the plugin will try to install npm in Apigee Edge)
--upload-modules
In order to compress node.js modules, it's required node directory to exist in the root folder. By default node_modules, public, and resources are generated as part of the build. Compress configuration in Gruntfile.js can be modified to include any other configuration.
This task comes disabled by default to prevent issues from OS environments (MacOS and Windows). To enable, remove comments from shell task in Gruntfile and customize as directions below.
JavaCallouts are currently supported by leveraging grunt-shell npm package. Therefore, compilation and packaging steps are dependent on your local installation of javac and jar tools. Source code directories must be located under java/src directory and any jar dependencies under java/lib directory. See Gruntfile.js shell task for more details.
Note: Since javac requires to know where .java files are located, it is required to include java callout separated by spaces in shell javaCompile target.
For instance:
javac -sourcepath ./java/src/**/*.java -d ./target/java/bin -cp java/lib/expressions-1.0.0.jar:java/lib/message-flow-1.0.0.jar:jar:java/lib/message-flow-1.0.1.jar **java/src/com/example/SimpleJavaCallout.java**
####String Ability to search and replace strings from text files that match any pattern in Regex or string. See grunt/search-and-replace-files.js to setup per environment. This task leverages grunt-string-replace module. See grunt/search-and-replace-files.js for an example.
####Include files from common Git submodule Ability to search and include content from files is also provided by string-replace task. See examples under grunt/search-and-replace-files.js that include fragments from common folder for fragments (multiple steps), policies, and JavaScript files. Note common folder leverages Git Submodule, which resides in a separate branch under the same repository. This allows reusing code across multiple APIs without adding more complexity.
This repo provides a guide for setting up an instance of Jenkins with Grunt to deploy and configure an API bundle.
This plugin is enabled to provide feedback about coding best practices for JavaScript.
JSHInt provides a large set of configurable (options)[http://www.jshint.com/docs/options/] that can be enabled out-of-the-box. See jshint task in Gruntfile.js
ESLint provides an pluggable framework to enable static code analysis. In contrast to JSHint, ESLint can be extended to write custom API specific rules. See conf/rules/if-curly-formatting.js rule and conf/eslint.json to manage alerts. See ESLint Gruntfile.js section
Grunt plugin can be extended to support plugins, shell script or any other command line tools. For instance Proxy Dependency Maven Plugin includes an example of a pom.xml.
If you would like to contribute, simply fork the repository, push your changes to a branch and send a pull request:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Typo fixes, improvements to grammar or readability, it's all welcome.
Copyright (c) 2014 Diego Zuluaga (twitter: @dzuluaga) Licensed under the MIT license.