As a developer, it’s very rewarding to work with beautiful APIs that just work. Half the battle of building applications against 3rd party APIs is having clear and concise documentation that show great examples. However, sometimes documentation doesn’t go far enough. Sometimes, having a tool that allows you to “touch and feel” the API is more productive. Having the ability to play with an API allows for greater discovery and can sometimes lead to better use.
At AtlasCamp in September, we demonstrated a prototype of a REST API “playground” that will allow developers to play with our REST APIs in a way that wasn’t possible before. I’m happy to announce that this new REST API Browser (aka, RAB) is now available in the Atlassian SDK.
The RAB is a plugin inside the SDK that allows you to browse through all of the REST API modules installed on a given Atlassian product. This is a great tool for browsing through and discovering the available REST resources available in the upcoming Jira 5.0 release — or just discovering what REST resources are available in a particular Atlassian product.
The nice thing about the RAB is that it also discovers any REST resources that plugin developers might have created. So, if you have a plugin installed that creates a REST resource, you’ll be able to use the RAB against those resources as well. Here’s what a sample request/response looks like:
As an added bonus, if you want to use Confluence’ JSON-RPC APIs, you can use the RAB for that as well. If the REST APIs uses the prescribed Javadoc annotations, you’ll also see inlined documentation inside the browser — down to the parameter descriptions.
Atlassian Developer Toolbox
As if the RAB wasn’t enough, we thought this would be a good time to package up a bunch of useful developer tools into one plugin that you can use day to day. We’re calling this plugin the Atlassian Developer Toolbox. It’s a project we’ve just started, so there’s not much available outside of RAB in this release of the SDK, but we’ve got a laundry list of useful tools that we’re working on that will be added as we complete them.
If you’ve got ideas for what tools we should include in this toolbox, please let us know below.
How do I start using the REST API Browser?
I’m glad you asked. For now, the RAB is packaged up in the Atlassian SDK (starting with version 3.6.2). You can download the latest SDK from here… or if you’re on a mac and use Homebrew, you can simply:
[ccN]brew install atlassian-plugin-sdk[/ccN]
From there, whenever you execute [cci]atlas-run[/cci], [cci]atlas-debug[/cci], or [cci]atlas-run-standalone[/cci] your environment will get started with the Developer Toolbox. You can access the RAB from Administration > Developer Tools > REST API Browser or simply by navigating to [cci]/[context]/plugins/servlet/restbrowser[/cci].
That’s it. We hope you enjoy playing with Atlassian’s REST APIs through this new tool. As always, if you have any comments or suggestions, pipe up below!