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


If you are already logged into your Google account, you will see a preview and ‘Use this template’ button below:-
(To use the template, login to your Google account and then refresh this page, and you will see a ‘Use this template’ button below)

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:

If you like this post, please share it with your friends

    • 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