Blog Archives

REST API documentation embedded in the application

Our development team has built a tool that documents an application’s REST APIs within the application itself. What’s more, you can test the REST resources and methods too. All from the application’s user interface. Now, that’s embedded help for nerds. 🙂 I’m writing this post because I think many technical writers and developers will be interested in this solution. It may trigger ideas about adding something similar to other applications too.

The tool is called the REST API Browser, and it is implemented as a plugin. At the moment, it is available only within the Atlassian Plugin SDK. In the future, you may be able to download the REST API Browser as a separate plugin and install it into any Atlassian application.

So, what does the REST API Browser do, what is the Atlassian Plugin SDK, and how can you get the REST API Browser to work within an Atlassian application?

Overview of the REST API Browser

This is what the REST API Browser looks like, when running inside an application called JIRA:

The /user/search REST resource in JIRA

JIRA is an issue tracker developed by Atlassian. The above screenshot shows one of the JIRA administration screens, part of the application’s user interface. I’m running JIRA on my local machine, in plugin development mode. The REST API Browser is available as one of the options on the application’s administration screens. It’s as simple as that.

In the screenshot, you can see the resources in the JIRA REST API, starting at the /user/search resource. For each resource, the REST API Browser shows the methods (GET, POST, PUT) and the parameters available.

You can even do real-time testing of the APIs, by submitting a request and seeing the response. In the screenshot below, I have run a GET request using the /user/search resource, asking for details of username “admin”. You can see:

  • A form, prompting you for the parameters relevant to the resource and method. In this case, the only parameter is the username.
  • The request, as formulated by the REST API Browser.
  • The response headers.
  • The JSON in the response body.

A REST request and response

The application’s REST APIs at your fingertips!

Which REST APIs does the Browser show?

The REST API Browser displays all the REST and JSON-RPC APIs available in the running installation of the application. That means all the remote APIs that are part of the application’s default installation (JIRA, in this case) as well as any additional REST APIs provided by a plugin.

So, if you install a plugin into JIRA, and that plugin exposes a REST API, the resources will show up in the REST API Browser too. Magic.

Introduction to Atlassian Plugin SDK

The Atlassian Plugin SDK is a tool for developers who want to create a plugin (add-on) for an Atlassian application. For example, you may want to add a new option to the Confluence page menu, showing all authors who have ever updated the current page. Or you may want to add a new option in JIRA that points to your organization’s intranet site.

But the SDK is useful even for people who don’t want to build a plugin. You can use the SDK to download and run an Atlassian application on your own machine, in plugin developer mode. One of the features that you get is the REST API Browser.

How can you get hold of such sweetness?

Here’s a quick start guide. First, install the SDK and use it to download and run your application:

  1. Follow the guide to installing the Atlassian Plugin SDK. Do just steps 1, 2 and 3. You can skip the last step, which sets up an IDE (Eclipse, IDEA or NetBeans), if you do not need a development environment.
  2. Create a directory in your file system to store the application executables. Let’s assume you want to run the REST API Browser in JIRA. Then, for example, you could create a directory called myjira.
  3. Open a command window.
  4. Go to the new directory that you just created, myjira.
  5. Run atlas-run-standalone --product APPLICATION. For example, atlas-run-standalone --product jira.
    Note:
    There are two dashes in front of the word product.

After following the above steps, you will have the application running on your computer. When all the downloads and installation are complete (which may take a while), you will see a message in your command window that includes the URL for the local installation of the application.

For JIRA, the message will look something like this:

[INFO] jira started successfully in 174s at http://localhost:2990/jira
[INFO] Type CTRL-D to shutdown gracefully
[INFO] Type CTRL-C to exit

Now you can access the application in your browser and use the REST API Browser from the application user interface:

  1. Go to your web browser and enter the URL given for your application. For example, http://localhost:2990/jira.
  2. Enter the username and password: admin / admin.
  3. Go to the application’s administration screen. For example, in JIRA: Click Administration at top right of the screen.
  4. Click REST API Browser on the administration screen.
  5. Choose an API from the dropdown list at the top left of the screen.
  6. Choose a resource from the list on the left of the screen.
  7. See the methods (GET, POST, PUT, etc) and the parameters available for that resource.
  8. To test the resource, enter the parameter values as prompted then click Execute.

The documentation has the details of running the REST API Browser in the SDK, and of viewing and testing the resources.

Getting technical: How the REST API Browser works

The source code is available on Bitbucket, as part of the Atlassian Developer Toolbox. The developer’s guide describes how to ensure that a REST API is included in the Remote API Browser. That document also gives a summary of how the browser is put together.

Pretty neat, huh

From a plugin developer’s point of view, the REST API Browser is very useful. From a technical writer’s point of view, I think it’s pretty revolutionary. Has anyone seen other examples of embedded REST API documentation?

Kudos to Rich Manalang and the Atlassian developer relations team for developing this shiny tool. Here is the blog post in which Rich announced it: Introducing the REST API Browser and the Atlassian Developer Toolbox.

Search tools for API documentation

Continuing my quest for the perfect API documentation, this week I came across a site that offers a search over a set of API documents: Rails Searchable API Doc. Have you seen it before, or anything similar or even better?

I’ve written a couple of posts recently about API documentation, talking about documenting REST APIs and using tests as examples. People have added a lot of very useful and thought-provoking information via comments on both posts. Thank you everyone! This time, I’d like to show you a site that Jean-Michel pointed me at.

sdoc for searching Ruby APIs

The Rails Searchable API Doc site is developed by Vladimir. As the name implies, you can use the site to search the Ruby on Rails API documentation. The site is built by Vladimir’s tool sdoc, that adds a search feature into the documentation generated by RDoc. RDoc builds HTML documentation from Ruby source code.

Vladimir’s sdoc code repository is on Github. Here’s the readme.

Try it out!

Go to http://railsapi.com/. Here’s the gist of what you will see:

Tools for searching API documentation

Rails Searchable API Doc

Select one of the options above the big buttons, to choose the APIs that you want:

  • Rails
  • Rails and Ruby
  • Build your own

If you choose to build your own, you will get a list of APIs to choose from:

Tools for searching API documentation

Rails Searchable API Doc – select your APIs

Make your choice, click “Browse online” to see the API documentation, then enter a search term to see the dynamic search working. It’s in the left-hand panel:

Search tools for API documentation

Rails API search

What I like about this search is that it’s immediate. You see the results as you type. A very nice addition is  that you can select one or more sets of API documentation to merge into the search.

The search is smart. The first few results show matches that start with the search term you entered. Then come the results where your term is embedded somewhere in the string. Finally it shows results that may be a match: the characters in your search term appear in the result, but not necessarily sequentially. The front page has a quick guide to the features of the search tool.

Pretty neat, huh.

I want an sdoc!

I’m wondering how much sdoc relies on the RDoc format, and how easy it would be to adapt it for documentation generated by other tools such as Jersey’s WADL generator, Javadoc, Sandcastle for .NET, Doc-O-Matic, Enunciate, Doxygen. I’ve written to Vladimir, asking him for his thoughts on this.

Have you seen similar search tools on other API documentation sites?

BTW, a good API doc site

This is nothing to do with searching, but it is part of the quest for the perfect API documentation. Daniel is a fan of the Facebook developer portal. I’m impressed too.

Writing REST API documentation

Recently I had the pleasure of working on some REST API documentation. I really enjoy this, because it is quite a change from the sort of thing I usually write. It’s highly technical stuff. The developers learned a lot while developing the code, and I learned a lot from working with them on the documentation.

Updated on Tuesday 11 February 2014: I’ve updated the links in this post, added a link to a tutorial, and removed some obsolete links, to reflect changes in the Atlassian documentation.

Most of the documentation was written by our developers, in particular Sam Le Berrigaud. My job was to massage the style and structure and add bits on the periphery.

Some bloggers have commented that there’s a fair amount of information available on the web about REST principles, but not much about actual implementations. We have published our REST API design guidelines. We’ve also added a document explaining how to use our REST plugin module to create REST APIs. (Added later: a tutorial on developing a REST service plugin.]

When we release our first product that uses the REST module in the wild, I’ll be able to link to more documentation about REST implementations. That will probably be Crowd 2.0, which will provide a REST API based on the REST plugin. I’ll let you know when that happens, because then we’ll have some documentation on using the API itself.

This is exciting stuff, especially when you start getting an inkling of how neat and powerful a REST API can be. That’s why I enjoy writing about it. It’s satisfying and rewarding to write about technology that is neat and tidy.

So, the developers and I have learned a lot. But I’m sure there’s more to learn. We know that we need to add information on installing the REST plugin and its dependencies, and some examples along the lines of this forum discussion.

If you have written REST API documentation or designed and worked with REST APIs, I’d be really interested to hear your ideas, both about the API design and about the documentation itself.

There’s nothing more RESTful than a tree 😉

Here’s a picture of my Prickly Paperbark tree. How it’s grown! It is now one year nine months old, the same age as this blog. I planted the tree in August 2007 — see how small it was then.

Writing REST API documentation

Writing REST API documentation

%d bloggers like this: