One of the greatest challenges that we face when we try to design API is balancing power, flexibility, complexity, extensibility and version tolerance. There is a set of tradeoffs that we have to make in order to make sure that we design an API, and selecting the right tradeoffs impacts the way that users will work with the software.
One of the decisions that I made about the docs db is that it would be actually have two published API. The first would be the remote API, accessible for clients, and the second would be a public API, accessible for people who want to extend the db. I consider extending the db to be a very common operation, for doing things like adding more functions for the views, supplying the sharding function, etc. I am assuming that most people who would want to do this extension would be .Net devs, so I am just going to use my usual style here and expose some extension points so it will be possible to mix & match things.
Currently I am thinking about an API similar to:
- POST or PUT to /docs[/id] – to create/update a document
- POST to /bulk_docs – to create/update a batch of documents
- POST or PUT to /views – to create / update a view definition
- GET from /docs/id to get a document
- GET from /views/name – to get all view docs of particular view
- GET from /views/name?key=foo – to get all view docs with matching key
- GET from /views/name?start=foo&end=bar – to get all view docs within range
This seems to be a pretty simple proposition, and it seems pretty complete.