Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,026 | Comments: 44,842

filter by tags archive

Designing a document databaseRemote API & Public API

time to read 3 min | 474 words

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.

For the remote API, we need a way to add / remove documents, get a document and query a view. I would like that part of the API to be accessible from any language, even if I don’t foresee it getting used much in other languages. The idea of being able to access it from JavaScript, and making the entire application hosted through the DB is actually a very interesting idea, see CouchApp for more details. Making it accessible for everyone is a pretty good idea, and I think that adopting’s a REST API similar to the one that CouchDB is using would be a good choice. Something that I would be extremely interested on, as a matter of fact, would be to make use of Astoria’s REST API, instead of having to write my own implementation. I think it bears some investigating, since on the minus side there is the problem that Astoria expects some sort of schema from the backend implementation, but it would be an interesting avenue for investigating.

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.


More posts in "Designing a document database" series:

  1. (17 Mar 2009) What next?
  2. (16 Mar 2009) Remote API & Public API
  3. (16 Mar 2009) Looking at views
  4. (15 Mar 2009) View syntax
  5. (14 Mar 2009) Aggregation Recalculating
  6. (13 Mar 2009) Aggregation
  7. (12 Mar 2009) Views
  8. (11 Mar 2009) Replication
  9. (11 Mar 2009) Attachments
  10. (10 Mar 2009) Authorization
  11. (10 Mar 2009) Concurrency
  12. (10 Mar 2009) Scale
  13. (10 Mar 2009) Storage



I see.. some REST like API. Do you care if you get the correlated ID back from a POST to /bulk_docs? If so, then do you assume a reply in the same order, or allows the client to specify the ID, or return the whole post content with ID's added?

Ayende Rahien


Probably just same order response of the ids.


How about delete? Would you use an HTTP DELETE or a POST to a delete url?

Ayende Rahien


Yes, delete should work


Hmm, where is the representational state transfer in that api ? :)

Ayende Rahien


documents are resources

uniquely addressable by their id

There are cachable, stateless and layered


Ayende, I'm sure you have read it: roy.gbiv.com/.../rest-apis-must-be-hypertext-dr...

I know, so much semantic buzz is around rest it makes people unrest, but I think the main concept (i.e. browsable API with single entry point) of representational state transfer missies many.


Addressing schemes to consider:

JsonQuery: [ www.sitepen.com/.../jsonquery-data-querying-bey... ]

Astoria: [ msdn.microsoft.com/en-us/library/cc668766.aspx ]

Google APIs (all of them more or less revolving around the same format): [ code.google.com/p/pyrfeed/wiki/GoogleReaderAPI ]

Implementations of document dbs:

  • SimpleDB

  • NSimpleDB

  • CoachDB

  • Persevere

Miscelanea :-)


Probably just same order response of the ids.


Or you could simply use OpenRasta...

That said, there is no such thing as an addressing scheme or predefined URIs in ReST. If you doucment what APIs to document with, that's a ReST smell. :)

Comment preview

Comments have been closed on this topic.


No future posts left, oh my!


  1. Technical observations from my wife (3):
    13 Nov 2015 - Production issues
  2. Production postmortem (13):
    13 Nov 2015 - The case of the “it is slow on that machine (only)”
  3. Speaking (5):
    09 Nov 2015 - Community talk in Kiev, Ukraine–What does it take to be a good developer
  4. Find the bug (5):
    11 Sep 2015 - The concurrent memory buster
  5. Buffer allocation strategies (3):
    09 Sep 2015 - Bad usage patterns
View all series


Main feed Feed Stats
Comments feed   Comments Feed Stats