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:

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

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.

7 Responses 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.

Leave a Reply

Entries (RSS)