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:

Of course, to design a good API you should take a look at existing APIs, and even use some of them:

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.

44 Comments to “How to design an API: best practises, concepts, technical aspects”

  1. SCE Says:

    Very useful information :) I see there are realy good tips. I am going to use some of them

  2. Fabio Says:

    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!

  3. Software geeks: How Piwik automatically generates the API, using PHP Reflection - Piwik Says:

    [...] If you're interested by this topic, see also the blog post: How to design an API? [...]

  4. Erdwärme Says:

    Is it possible to get an Api to Joomla Framework? Thanks for reply

  5. Catalin Nichita Says:

    Erdwärme i think is not possible to get an API to Joomla.
    The post is very interesting. Thank you for these infos !

  6. Walter Kirch Says:

    The slides presentation by Google really makes you think, thank you for sharing!

  7. Amit Pbx Says:

    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.

  8. Sandy Saini Says:

    I have been browsing throught your site. I find it very informative and very helpful.

    Great post!

  9. Jacques | Web Design Says:

    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.

  10. Adirec Torytski Says:

    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 :)

  11. Kim From The Promo Directory Says:

    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.

  12. Web Design New York Says:

    An interesting and info post. Thanks for sharing this article.

  13. Jose Luis Says:

    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.

  14. links for 2009-09-17 | Visualrinse | Design and Development by Chad Udell Says:

    [...] 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 [...]

  15. sc-seo Says:

    Ebay API , yes it's impressive!! haha……

  16. Mike Says:

    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

  17. watch alice in wonderland online Says:

    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.

  18. watch alice in wonderland online Says:

    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.

  19. watch alice in wonderland online Says:

    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.

  20. watch alice in wonderland online Says:

    Thanks a lot for sharing your insights.

    APIs have definitely become a great distribution channel and potentialy a new source of revenues.

  21. Pinoy Says:

    This is indeed a helpful piece of article for our community. Hopefully, we can adopt it.

  22. increase free testosterone Says:

    This was a Excellent write up, have a awesome day.

  23. watch kick-ass online Says:

    I have just came across this site and have so far found it very interesting and informative.
    Thank you for the great posts!

  24. Sanya Says:

    Interesting post! Thanx

  25. lara Says:

    Just designed my first API :)

  26. Angie Says:

    That's really cool Lara!! :)

  27. Angie Says:

    I will try now! :D

  28. Autismus Says:

    wow, i am from germany and did not know this webpage. very useful information and i would never find on german websites. thany you!

  29. Dragon Says:

    I will try too! :)

  30. Novuss Says:

    great information about that stuff. thanks!

  31. Maya Says:

    Awesome information!

  32. lederpuschen Says:

    Thanks for the information! Your blog is very helpfull! Good job.

  33. Rose Says:

    I love this article!

  34. Bob Says:

    thanks this is great!

  35. sam Says:

    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.

  36. Watch TV Shows Full Length Online Says:

    this post really gave me some idea…thanks for the input

  37. Dave Says:

    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

  38. ajm web design Says:

    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

  39. B&B Portugal Says:

    Thank you. I have enjoyed reading this article and found it really useful.

  40. Alex Says:

    Just designed my first API,thanks a lot :)

  41. half marathon training Says:

    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.

  42. marathon training Says:

    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 ]

  43. marathon training Says:

    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

  44. Karl Foxley Says:

    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. :)

Leave a Reply

Comment moderation is enabled. Your comment may take some time to appear.

Entries (RSS)