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?

Incoming search terms:

  • john

    Might want to add a testing section to each as well. Simple input data with expected results is all that is really needed

  • Good job Saurabh – almost what I was looking for.


  • jim

    put it also somewhere besides google.
    I love google-docs, but i cant access them from work…..

  • Jsx

    I tried. But since the doc is designed inside Google Docs, it didn’t look the same when exported as a standalone doc. The problem is that you need to be signed into your personal Google/Gmail account (not Google Apps) to access the doc.

  • Rocha D’ Souza

    Concise and clean, thanks for this template!

  • Akshina

    Hi, I am also looking for a template for my web service design and i found your blog while searching for it. I am also looking for the one with the same goals as you have. however, i couldn’t open the link ‘Web service API Specification Document Template’. Can you please help me on how to access this link?

    Still I am not seeing ‘use this template’ button after creating an account and logged into Google and refreshed the page for a couple of times.

    I appreciate your help.
    Thank you

  • Jsx

    Hi Ashina, did you try after logging into a normal Google account (GMail) or a Google Apps account? You need to try with a normal Google/GMail account.

  • Jsx

    Well, I’ve made a copy of the doc and shared it with your Gmail id. You should must have gotten a link in your email to access it.

  • Akshina

    Thank you very much for your prompt response and efforts to make it available to me. When i try to get it from the Google drive, i got the below error. I am not sure whether the issue is on my side or not,

    Google Drive
    The app is currently unreachable

  • Akshina

    Is this the complete one?

  • Akshina

    Is this the complete one? If so, it is very simple and concise, i liked it. Thanks for your help.

  • Jsx

    Yeah, that’s the doc. Glad you liked it.

  • Matthew Yarlett

    Nice template. Thanks for sharing it!

  • Richa Arora

    hi, can u please share the same with me as well as i also require it for my reference and i am also facing the same issue mentioned above.

  • Jsx

    Done πŸ™‚

  • sunny vegas

    This template is “bae”….. awesome!

  • Jsx

    Glad you like it πŸ™‚

  • Thunder

    Thanks for sharing

  • Acekyd

    Hi, plz share with me too @ tommybosgust@gmail.com

  • Jsx

    Hey, if you are unable to use the template by clicking the ‘Use this template’ button in the article above, you can access the template at https://docs.google.com/document/d/1HSQ3Fe77hnthw8hizqvXJU-qGEPHavMkctvCCadkVbY/edit?usp=sharing (Let me know if you are still unable to access it)

  • Kelly

    Hi – can you send me the doc as well? Kelly.sable@gmail.com, thanks!

  • Jsx
  • Kelly

    I am not able to login to it, it might be because I am at work, I can try from my home laptop too