Share

From this page you can share Wishlist for a great Ajax API to a social bookmarking site or email a link to the page.
Social WebE-mail
Enter multiple addresses on separate lines or separate them with commas.
Wishlist for a great Ajax API
(Your Name) has forwarded a page to you from Ajaxonomy
(Your Name) thought you would like to see this page from the Ajaxonomy web site.

Wishlist for a great Ajax API

Tagged:  

Over at Wait till I come! they have written a good post about a wishlist for a great Ajax API. The list is very interesting and if you are writing an Ajax API, then this is a good post to read.

Below is an excerpt from the post.

Designing a great Ajax API

As an example I will use the recently released Google translation API, point out its good parts and list things I consider missing. I will not go into the part of actually writing the API but instead explain why I consider the missing parts important. This is not an attack towards Google, I just really liked working with this API and wanted to have it a bit easier to use, so no hard feelings, I really take off my hat that you offer an API like that!

Here are the points I consider important when we’re talking about Ajax APIs in JavaScript (Ajax implies that but you’d be surprised how often a REST API is advertised as Ajax):

  • Good documentation
  • Usage examples to copy + paste
  • Modularity
  • Link results to entries
  • Offer flexible input
  • Allow for custom object transportation
  • Cover usability basics

Documentation and presentation

Let’s start with a positive: the documentation of the Google Ajax Language API is great. You have all the information you need on one page including copy and paste examples. This allows you to work through the API online, read it offline and even print it out to read it on a crowded bus without having to take out your laptop.

Tip: If you are offering copy and paste examples – which by all means you should as this is what people do as a first step – make sure they work! I learnt the hard way in my book Beginning JavaScript with DOM Scripting and Ajax that there is nothing more dangerous than showcasing code snippets instead of full examples – people will copy and paste parts of a script, try to run it and either email you that your code is broken or – even worse – complain in book reviews on Amazon. If you offer copy and paste examples make sure all of them work independently.

Google offer explanations what the API is, what you can do with it, a list of all the parameters and what they mean. This is great for a first-glance user. For the hard-core audience they also offer a class reference.

You can read the full post here.

I'm thinking of writing some Ajax APIs for some of the applications in our labs section and this post has some good information that I will be using for these APIs.