Mailing-List: contact couchdb-user-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: couchdb-user@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of msciab@eprometeus.com
 designates 213.156.62.149 as permitted sender)
Message-ID: <48CD9803.7080103@eprometeus.com>
Date: Mon, 15 Sep 2008 01:02:27 +0200
From: Michele Sciabarra <msciab@eprometeus.com>
Reply-To: michele@sciabarra.com
User-Agent: Thunderbird 2.0.0.16 (Macintosh/20080707)
MIME-Version: 1.0
To: couchdb-user@incubator.apache.org
Subject: A modest proposal for a Couch Erlang API
Content-Type: text/plain; charset=ISO-8859-15; format=flowed
Content-Transfer-Encoding: 7bit

Damien stated that the Erlang API should be simply documenting some 
internal functions of CouchDB.

I tried this approch and documented it in my blog 
(http://www.sciabarra.com/cp/2008/09/06/1220695020000.html)

Anyway I observed that is a bit dispersive. This is because of course 
the the various features are implemented in different modules.
It is not simple nor elegant documenting  a bunch of various functions 
in those modules, and the expose details are too often low level.

So I realized a sort of simplified wrapper was needed. As I was 
suggested, I started to see the httpd api and definitely I had the idea 
that an API, erlang or not, shoud mimic the httpd api.

As a general rule, to get the api I used the HTTP verb (get, post, put ) 
, added a suffix that is the "_xxx" meta operation when available, 
otherwise adding an arbitrary but descriptive suffix.

This is the result of my efforts:

% List all database
get_all_dbs()

% Generate a new unique id
post_uuid()

% Generate Count new unique id
post_uuid(Count)

% Create a database
put_db(DbName) when is_binary(DbName)

% Delete a database.
delete_db(DbName)

% Informations on a database
get_status(Db)

% Compact the database
compact_db(Db)

% All documents
get_all_docs()
get_all_docs(Start, Count)
get_all_docs(Start, Count, Desc)

% Get a document
get_doc(Db, Doc)
get_doc(Db,Doc,revs)  % with revisions
get_doc(Db,Doc,Rev)   % of the specified revision

% Get an attachment
get_attachment(Db, Doc, Attachment)

% Create a new named document
put_doc_named(Db, Doc, Term)

% Insert or Replace and attachment
put_attachment(Db, Doc, Attachment) % insert
put_attachment(Db, Doc, Attachment, Rev)  % replace the given revision
  
% Create an unnamed document
post_doc(Db)    

% Bulk insert/update
post_bulk_docs(DbName, Docs)


A good start for implementing this api is the couch_http.erl. Actually I 
started to code it, and I am willing to contribuite it.
 But I am here asking if my proposed API could be acceptable.