Jan 5, 2013    |       23 comments

Web service API Specification Doc Template

Finally I got sick with the webservice spec documents we were using at my previous employer. I searched all over the web for a document template that I could use for laying out our new web service’s API specification. I found several ones – good and bad -, but none were up to my expectations. So I decided to create a document template myself. My key design goals were the following:-

  • Ease of use
  • Clear
  • Concise
  • Not boring to look at.

I finally came up with a document template that I (and my colleagues) liked. Hope you find it useful too. Its created in Google Docs and shared ‘publicly’, so you can easily copy it and use it for your own projects.

See it in action -> Web service API Specification Document Template

 

Click here to use the template

(To use the template, make sure you are logged into your Google/Gmail account and click the above link. You should see a ‘Use this template’ button on the right top corner of the page.)

Tips for use:-

  1. Be consistent
  2. Use colors, fonts, font size etc to visually distinguish and classify things.
  3. Use fixed width fonts (courier, monospace etc) for showing code.
  4. Don’t clutter it up with too many colors and fonts.
  5. Managing and updating a good document is not very easy; but remember, everything worth doing is difficult anyway!

So what do you think? Like it? Where do I need to improve it?

23 Comments