Erlang API Discussion

[Ben Browning <be...@gmail.com>]

A prerequisite for partitioning and a general nice-to-have feature is
an Erlang API for CouchDB. Let's get the discussion going; I'd love to
see an initial version of the API included with the 0.10 release.

The API will overlap quite a bit with the code in couch_http_db.erl,
couch_http_view.erl, etc. I propose refactoring this code into the
Erlang API methods and having the couch_http_*.erl files use the
Erlang API. This helps us reduce code duplication and will allow us to
test the Erlang API with the existing HTTP tests.

For the initial version of the API, I'd prefer to only expose a subset
of the HTTP API. Document CRUD methods are an obvious one and at least
a basic form of view queries would be nice. The Erlang API needs to be
just as stable, if not more stable, than the HTTP API - I'm open to
implementing more or less pending reasonable discussion.

The parameters passed in and data returned from the API should be
well-defined. I propose any complex data structures given as input or
returned from the API be records defined in couch_db.hrl or another
appropriate place. There are already records defined here for
documents and view query arguments, which might be all we need.

This should be enough to spark an initial discussion. I'll create a
page on the wiki for the API proposal to consolidate some of the
information once other people give their input.

Thanks,

Ben

Re: Erlang API Discussion

[Chris Anderson <jc...@apache.org>]

On Thu, Mar 5, 2009 at 4:43 PM, Ben Browning <be...@gmail.com> wrote:

> I like the idea of growing the API as needed. It sounds like you feel
> we could get by with an initial API that just allows you to retrieve a
> document and update a document. Is that accurate?
>

Or lists of documents, which would probably be even easier to code.

-- 
Chris Anderson
http://jchris.mfdz.com

Re: Erlang API Discussion

[Ben Browning <be...@gmail.com>]

On Thu, Mar 5, 2009 at 7:29 PM, Chris Anderson <jc...@apache.org> wrote:
> I'm not sure having the HTTP wrapper use the API is the best plan, as
> it might turn out to be indirection for indirections sake. If it turns
> out to be simpler to use the Erlang API, then of course lets do, but
> if it is slower or more confusing, than we shouldn't feel like we have
> to.

I'm fine with this, with the caveat that I'd like to reduce code
duplication as much as practical. A good first step could be to write
the Erlang API and later modify the HTTP API to use it if it makes
sense.


> +1 to keeping it limited to document CRUD on the first round. View
> queries will be harder to model as they rely on sending side-effects
> out the HTTP socket (maybe replace http socket with gen-server reply?)

I've been trying to figure out for the last few days exactly how view
queries would work in the Erlang API. If we don't have the HTTP API
rely on the Erlang API this becomes much easier and I'm sure we could
come up with a good solution.


> Internally, all database operations are updates, and they are all bulk
> (sometimes with bulk size of 1). I'm not sure how much we want to hide
> this from the user. It might be better to keep the API wrapper thin,
> so the user sees this. Then we can potentially add wrappers so you
> don't have to remember what the structure of a delete is, for
> instance.

I like the idea of growing the API as needed. It sounds like you feel
we could get by with an initial API that just allows you to retrieve a
document and update a document. Is that accurate?

Re: Erlang API Discussion

[Chris Anderson <jc...@apache.org>]

On Thu, Mar 5, 2009 at 4:16 PM, Ben Browning <be...@gmail.com> wrote:
> A prerequisite for partitioning and a general nice-to-have feature is
> an Erlang API for CouchDB. Let's get the discussion going; I'd love to
> see an initial version of the API included with the 0.10 release.
>
> The API will overlap quite a bit with the code in couch_http_db.erl,
> couch_http_view.erl, etc. I propose refactoring this code into the
> Erlang API methods and having the couch_http_*.erl files use the
> Erlang API. This helps us reduce code duplication and will allow us to
> test the Erlang API with the existing HTTP tests.

I'm not sure having the HTTP wrapper use the API is the best plan, as
it might turn out to be indirection for indirections sake. If it turns
out to be simpler to use the Erlang API, then of course lets do, but
if it is slower or more confusing, than we shouldn't feel like we have
to.

>
> For the initial version of the API, I'd prefer to only expose a subset
> of the HTTP API. Document CRUD methods are an obvious one and at least
> a basic form of view queries would be nice. The Erlang API needs to be
> just as stable, if not more stable, than the HTTP API - I'm open to
> implementing more or less pending reasonable discussion.

+1 to keeping it limited to document CRUD on the first round. View
queries will be harder to model as they rely on sending side-effects
out the HTTP socket (maybe replace http socket with gen-server reply?)

Internally, all database operations are updates, and they are all bulk
(sometimes with bulk size of 1). I'm not sure how much we want to hide
this from the user. It might be better to keep the API wrapper thin,
so the user sees this. Then we can potentially add wrappers so you
don't have to remember what the structure of a delete is, for
instance.

Chris

-- 
Chris Anderson
http://jchris.mfdz.com