How to design an API: best practises, concepts, technical aspects
When I started to design Piwik I read a lot about APIs, software architecture, service oriented architecture (soa), etc. I really wanted to design a modular architecture that would make it easy to request any data and perform any action from outside the user interface.
Technically speaking, Piwik has been built on the top of Apis. Everything that does some logic in Piwik is available through an API. We basically open all these APIs via a REST API. Of course you must authenticate for some calls eg. when deleting a user. In the user interface, AJAX requests are directed to the API module that returns data in HTML or JSON format (javascript friendly).
Here are the main concepts I tried to apply when designing the API:
- Easy to learn ; the documentation provides simple examples, complete documentation
- Easy to use ; single entry point, standard parameters
- Hard to misuse ; explicit error message suggesting parameters values
- Appropriate to audience ; I talked about such a service with several users, and looked at what the competition was offering
Interesting resources that helped me have a better understanding of the topic:
- How to design a good API and why it matters? Great PDF presentation by a google engineer that I really enjoyed
- How to add an API to your webservice? Interesting read
- Audience drived based API design
- The art of building a reusable class library. A great presentation by a microsoft engineer ; be ready for the 237 slides!! (that's a reason you end up working for microsoft when you like powerpoint so much!)
Of course, to design a good API you should take a look at existing APIs, and even use some of them:
- A great example: Flickr API ; see an example of a method documentation ; try the API explorer for this method
- Mediawiki API
- A more complex example: Ebay API ; see an example of a method documentation (yes it's impressive!!)
- A directory of existing APIs on programmable web
- Amazon API: example of the method ItemSearch
- And last but not least the Piwik API ; the best web analytics API that makes it easy to request anything from your best keywords, your top pages or the number of visits of the last 30 days, yesterday, or the previous 5 months. Give it a try.
If you have good resources or advice, feel free to post a comment. Good luck designing your API!
This entry was posted by Matthieu on Saturday, January 19th, 2008 ; category Documentation ; RSS comments.
English
Français 
Deutsch 
Italiano 
Fan Piwik on Facebook
Follow Piwik on Twitter
Follow Piwik blog
March 30th, 2008 11:37 am
Very useful information :) I see there are realy good tips. I am going to use some of them
February 2nd, 2009 6:33 pm
Thank you for sharing this. It helped me a lot! Especially the slides by the Google engineer are an interesting read.
Piwik has some of the nicest code I have seen in an open-source php project in a while. Keep up the good work!
February 4th, 2009 3:18 am
[...] If you're interested by this topic, see also the blog post: How to design an API? [...]
February 22nd, 2009 4:12 pm
Is it possible to get an Api to Joomla Framework? Thanks for reply
June 13th, 2009 7:35 pm
Erdwärme i think is not possible to get an API to Joomla.
The post is very interesting. Thank you for these infos !
June 22nd, 2009 11:54 pm
The slides presentation by Google really makes you think, thank you for sharing!
June 24th, 2009 9:55 am
I always break my head what is API and how to use it.
Thanks to your post now things are a bit clearer for me
Many thanks.
July 8th, 2009 9:03 am
I have been browsing throught your site. I find it very informative and very helpful.
Great post!
July 22nd, 2009 10:15 am
The application programming interface is of paramount importance if you desire to tweak or program, and this article is useful in helping one determine an effective baseline. Some of the links are downright handy too, and I thoroughly enjoyed the little dig at Microsoft and their Powerpoint crazy engineer. It is worth sitting throught the slideshow though.
July 26th, 2009 8:03 pm
there's sooooooooo much to learn about web design … API's ??? I've read some about it, but no idea how they work … I need a second brain :)
July 29th, 2009 10:06 am
I have just come across this site and have so far found it very interesting and informative. I had absolutely no idea about how much actually goes into web design, all we can do is learn learn and see how one goes.
Thank you for a great post and I hope to ponder through your site again.
August 5th, 2009 10:11 am
An interesting and info post. Thanks for sharing this article.
August 25th, 2009 10:22 pm
Thanks a lot for sharing your insights.
APIs have definitely become a great distribution channel and potentialy a new source of revenues.
To enable solid relationships with users and providers, APIs need a good design but also a management infrastructure.3scale (http://www.3scale.net) lets you set up a full developer portal, key management, analytics and also billing and payments.
September 18th, 2009 12:07 am
[...] del.icio.us openide: How To Design a (module) API How to design an API: best practises, concepts, Create Custom Filters Using the Pixel Bender Baseline – a designer framework by jQuery Sparklines [...]
September 30th, 2009 3:17 am
Ebay API , yes it's impressive!! haha……
October 17th, 2009 9:15 am
This article is very interesting. We use the Piwik API already around the data of our customers to evaluate and to explain be able. Great work. Thanks
January 6th, 2010 8:54 pm
The application programming interface is of paramount importance if you desire to tweak or program, and this article is useful in helping one determine an effective baseline. Some of the links are downright handy too, and I thoroughly enjoyed the little dig at Microsoft and their Powerpoint crazy engineer. It is worth sitting throught the slideshow though.
January 6th, 2010 8:54 pm
I have just come across this site and have so far found it very interesting and informative.
Thank you for a great posts and I hope to ponder through your site again.
January 6th, 2010 8:56 pm
I have just come across this site and have so far found it very interesting and informative. I had absolutely no idea about how much actually goes into web design, all we can do is learn learn and see how one goes.
January 6th, 2010 9:09 pm
Thanks a lot for sharing your insights.
APIs have definitely become a great distribution channel and potentialy a new source of revenues.
February 6th, 2010 5:16 am
This is indeed a helpful piece of article for our community. Hopefully, we can adopt it.
February 21st, 2010 1:10 am
This was a Excellent write up, have a awesome day.
March 29th, 2010 4:25 pm
I have just came across this site and have so far found it very interesting and informative.
Thank you for the great posts!
April 5th, 2010 12:00 am
Interesting post! Thanx
April 13th, 2010 7:43 pm
Just designed my first API :)
April 26th, 2010 12:09 pm
That's really cool Lara!! :)
April 26th, 2010 12:10 pm
I will try now! :D
May 2nd, 2010 3:59 pm
wow, i am from germany and did not know this webpage. very useful information and i would never find on german websites. thany you!
May 5th, 2010 11:27 am
I will try too! :)
May 7th, 2010 10:37 pm
great information about that stuff. thanks!
May 14th, 2010 1:25 pm
Awesome information!
June 3rd, 2010 2:53 pm
Thanks for the information! Your blog is very helpfull! Good job.
June 6th, 2010 7:33 pm
I love this article!
June 22nd, 2010 7:46 pm
thanks this is great!
July 7th, 2010 11:56 am
The application programming interface is of paramount importance if you desire to tweak or program, and this article is useful in helping one determine an effective baseline. Some of the links are downright handy too, and I thoroughly enjoyed the little dig at Microsoft and their Powerpoint crazy engineer. It is worth sitting throught the slideshow though.
July 14th, 2010 5:37 pm
this post really gave me some idea…thanks for the input
July 14th, 2010 10:19 pm
Good Tutorial, took 20 mins to read about but is surely gonna help me.APIs have definitely become a great distribution channel and potentialy a new source of revenues.Regards, Dave from VoIP Guide
July 25th, 2010 8:09 pm
Hi, I am fairly new to web design and seo, so programming might take a while longer as the code is so different…but with the help of sites like this anything is possible.
Thanks
July 30th, 2010 10:12 am
Thank you. I have enjoyed reading this article and found it really useful.
August 4th, 2010 3:03 am
Just designed my first API,thanks a lot :)
August 7th, 2010 8:53 am
Nice and informative and educational post and the most interesting and informative post I've ever seen, so the post bookmared my browser for future visits.
August 12th, 2010 5:31 am
Nice! Now I know what to do, thank you! And as this information is educational so this site has been added to my RSS feed for later browsing. To know more about
marathon training visit: marathontrainingschedule.net
[ marathon training ]
August 12th, 2010 5:35 am
Nice! Now I know what to do, thank you! And as this information is educational so this site has been added to my RSS feed for later browsing. To know more about
marathon training visit: marathontrainingschedule.net
August 24th, 2010 8:44 pm
Thanks for linking out to the resources that you have, you've just made my research that whole lot easier. I see this is a post published in 2008 so I wonder how much has changed in that time… I guess I'll have to see where the links take me; the great thing about the inter-connectivity of the web. :)