ap3

ap3: Node.js package for Express based Atlassian Add-ons

ap3 is a toolkit for creating Atlassian Add-ons with Node.js. Plugins 3 is a new kind of Atlassian add-on framework that works with Atlassian OnDemand applications.

Atlassian Remote Add-ons run inside a web server and communicate with the host Atlassian applications entirely by HTTP. The ap3 package helps you get started developing add-ons quickly, using Node.js and Express as the add-on server.

It's important to understand that Express by itself is a web app framework for Node. ap3 just provides a set of middleware and convenience helpers that make it easier to build Atlassian Add-ons. Specifically, ap3 adds:

• An optimized dev loop by handling registration and deregistration to consuming host for you at startup and shutdown
• A filesystem watcher that detects changes to atlassian-plugin.xml. When changes are detected, the add-on is re-registered with the host(s)
• Automatic OAuth authentication of inbound requests as well as OAuth signing for outbound requests back to the host
• Automatic persistence of host details (i.e., client key, host public key, host base url, etc.)
• Localtunnel'd server for testing with OnDemand instances

Getting Started

The fastest way to get started is it install the ap3-cli tool. The CLI makes it possible to generate an ap3 enabled add-on scaffold very quickly. To install:

npm i -g ap3-cli

Once installed, check out the README.

Recipes

How to configure config.js

How to use atlassian-plugin.xml

How to secure a route with OAuth

How to send a signed outbound HTTP request back to the host

Getting Help or Support

The ap3 tools are currently experimental. With that said, feel free to report issues. If you want to learn more about Atlassian's Plugins 3 framework, you can visit https://developers.atlassian.com.

Contributing

Even though this is just an exploratory project at this point, it's also open source Apache 2.0. So, please feel free to fork and send us pull requests.