Blog Archives

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

My trees and this blog are one year old

In August last year, I planted two trees at about the same time as I started this blog. Now the trees and this blog are just over a year old. A good opportunity for some stats 🙂

ffeathers

WordPress says that ffeathers has:

  • 62 posts
  • 184 comments
  • 184 tags (hmm, interesting but meaningless coincidence)
  • 17,216 total views
  • 7,584 blocked spam comments (thank you Akismet)

The most popular post is The agile technical writer with 1,247 views.

Today, someone found ffeathers by Googling for:

“your mouse has moved” error

I hope you found what you were looking for 🙂

Prickly Paperbark

Yesterday, another person came here searching for:

paperbark tree information on growth

So in your honour, here’s some idea of what a Paperbark tree does in a year.

The Prickly Paperbark was a tube, about 40cm high, when I planted it in August last year. Now it’s nearly 2 metres high and quite robust. (It needs to be robust, to survive the onslaught of weeds, floods, cold and heat that our garden inflicts upon it.)

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark now, at 198cm

Prickly Paperbark now, at 198cm

It has a very pretty trunk and bark already. The diameter of the trunk is almost 3cm at its thickest part.

Prickly Paperbark close-up

Prickly Paperbark close-up

Old Man Banksia

The Banksia has not grown much since I last measured it in April this year. It’s approximately one metre tall, and battling an ever-changing environment. Since I planted it, a couple of tree ferns have muscled in on the territory.

Old Man Banksia last year, at 17cm

Old Man Banksia last year, at 17cm

Old Man Banksia now, at approx 1 metre

Old Man Banksia now, at approx 1 metre

Still, it is putting up a gallant fight. Its trunk is almost 2cm in diameter and it always has a lot of new growth, although much of it goes sideways in an attempt to find the sun.

Old Man Banksia close-up

Old Man Banksia close-up

As well as my two favourites, we planted around 20 native trees and shrubs last year. Spring has sprung, and we’ll be shopping for more soon. Death to all agapanthus 😉

My Prickly Paperbark tree

This is a special edition of the ffeathers blog, to report the spectacular growth of my Prickly Paperbark tree since I last blogged about it approximately a month ago.

On 13 April, the tree was 172 cm. Today it’s 188 cm — grown 16 cm in five weeks! It’s now over 6 foot and taller than I am. I planted it in August last year, so it’s about nine months old.

Alas, it’s not only the Paperbark that has been growing. I spent a couple of hours this morning removing the Asthma Weed and Wandering Dew that had draped themselves all over the tree and its neighbourhood. Don’t gardens ever take a rest period in Sydney?

Just to reassure anyone who might be concerned about the Old Man Banksia I planted at the same time as the Paperbark: It’s doing fine too. It hasn’t grown so spectacularly since my last post a month ago, so it doesn’t warrant a special edition 😉

My Prickly Paperbark tree

Here’s a closeup of the trunk, with a peg for perspective:

My Prickly Paperbark tree

Found the ‘Web Developer’ add-on for Firefox

Web Developer is an awesome Firefox add-on by Chris Pederick. Here’s what the toolbar looks like:

Web Developer Toolbar

With just two clicks, you can resize your window to 800×600. Or you can choose a custom size. This is a must for conscientious web content writers – after all, we may be working in warpsize screen resolutions, but we still need to cater for people on stone-age systems.

Other useful features in Web Developer:

  • Make the browser draw an outline around various page elements, like frames or headings.
  • View a document outline – a sort of hierarchical list of headings and things, much like you can do with Microsoft Word.
  • Look at the stylesheets.
  • Show image information right on the page.
  • And so on – there’s something for everyone.

Thanks Chris – great stuff.

Back to my little trees

(See my previous blog post.) Hey, the trees are the same age as this blog! My blog is two weeks old today. That’s gotta mean something. Every so often, I’ll compare the blog’s progress with the trees.

We’ve just been out and planted the trees. It’s pouring torrents here in Sydney, so we got drenched. Here are some photos of the baby trees before planting:

Prickly Paperbark Prickly Paperbark – the baby tree with a peg to show relative size.
Prickly Paperbark Prickly Paperbark – close-up of the trunk. It’s pretty even now. When the tree grows, the bark will be silver and very flaky.
Prickly Paperbark Saw Banksia, a keystone source of nectar for birds and animals here in Sydney.
%d bloggers like this: