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 ther user interface, the AJAX requests are directed to the API module that returns data in HTML or JSON format (javascript friendly).
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 had chats about such a service with several phpmyvisites users, and I 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 have 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
This entry was posted on Saturday, January 19th, 2008 ; category Documentation ; RSS comments.
March 30th, 2008 at 11:37 am
Very useful information :) I see there are realy good tips. I am going to use some of them
February 2nd, 2009 at 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 at 3:18 am
[...] If you're interested by this topic, see also the blog post: How to design an API? [...]
February 22nd, 2009 at 4:12 pm
Is it possible to get an Api to Joomla Framework? Thanks for reply
June 13th, 2009 at 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 at 11:54 pm
The slides presentation by Google really makes you think, thank you for sharing!
June 24th, 2009 at 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 at 9:03 am
I have been browsing throught your site. I find it very informative and very helpful.
Great post!
July 22nd, 2009 at 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 at 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 at 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 at 10:11 am
An interesting and info post. Thanks for sharing this article.
August 25th, 2009 at 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 at 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 at 3:17 am
Ebay API , yes it's impressive!! haha……
October 17th, 2009 at 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 at 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 at 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 at 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 at 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 at 5:16 am
This is indeed a helpful piece of article for our community. Hopefully, we can adopt it.