We are a website monitoring company http://www.verelo.com and we're just starting to look at getting together our public API. We want people to LOVE it, not just "put up with it". Nothing makes me sad like an API that isn't practical...
We already have an internal API used by our app and all the monitoring nodes. Having created this internal API has been great, it adds a nice layer of abstraction and taught us a lot about the creation of API's which are used at scale (many thousands of requests per minute, maybe even per second by now, go through our internal API). Its written in PHP (shock, horror!!) but has done quiet well by us and I think it will live on for a while to come.
We plan to make a REST based API that responds in json....but nothing is in stone until we get more feedback.
Here are some questions to try frame the responses, but feel free to deviate...we're just looking for honest feedback.
1. Whats the one big thing you would suggest we consider when making this API?
2. What is the one big thing you would suggest we don't do?
3. Do you have any examples of API's you like or don't like to work with today? Why do you like or not like them?
4. Are there any frameworks etc you suggest we look at (We're only using PHP & Java today so i would like to avoid introducing a new language)?
Functions we plan to expose initially will do the following:
- Create a monitor
- Delete a monitor
- Edit a monitor
- Get recent results within a time period, and optionally of a certain type (possible types are pass,fail)
- Pause a monitor
- Un-pause a monitor
- Get a list of all monitors (and return some associated details of each)
1. We plan to include the documentation for the API at the root of the API i.e. https://api.verelo.com will serve up the API spec.
2. One thing that I want to ensure we avoid is simply having return values that are not explained anywhere in the documentation, Facebook drives me nuts for this reason.
3. The main API i've worked with recently has been Facebook. I love how much info it exposes, but i hate how much it changes and the lack of documentation. There are also a bunch of surprise functions in there, very frustrating.
4. We use a lot of Zend functions today, the Zend framework is my initial thought...