Skip to content
Browse files

fixed README typos

  • Loading branch information...
1 parent b39522a commit 49d473c5d45713f12d08edcb99a58c634d5f9da4 @dgreisen committed Nov 20, 2011
Showing with 17 additions and 14 deletions.
  1. +17 −14 README.md
View
31 README.md
@@ -13,7 +13,7 @@ Simply import YACA, and call the factory function. The factory function introspe
It is that simple.
## General Design ##
-YACA was designed for CouchDB databases where the number of databases and the design documents remain relatively stable. As such, the structure of the database is cached, and the api is generated from this cached structure unless `update: true` is explicitly passed to the factory. In a future release, YACA will be able to introspect DB changes at will; however, currently, you must create a new couchdb_api instance with the api_factory every time the database is added/removed, or a design document is modified.
+YACA was designed for CouchDB databases where the number of databases and the design documents remain relatively stable. As such, the structure of the database is cached, and the api is generated from this cached structure unless `update: true` is explicitly passed to the factory. In a future release, YACA will be able to introspect DB changes at will; however, currently, you must create a new couchdb_api instance with the api_factory every time a database is added/removed, or a design document is modified.
YACA is based on Mikeal's [request](https://github.com/mikeal/request/) module. Therefore, with a few exceptions listed below, api commands accept an options
argument and a callback. They return an error, the original response, and the parsed JSON body. Because it is based on request, you can do fancy things like piping, etc. made possible by Mikeal's module. See <https://github.com/mikeal/request> for more info.
@@ -25,7 +25,7 @@ argument and a callback. They return an error, the original response, and the pa
## Usage ##
### 1. Generate API ###
-The database can be introspected at runtime using the asynchronous `api_factory`. When this function is called, the database is introspected, an api is constructed, and a cache of the CouchDB structure is saved. The synchronous `api_factory_sync` can use a cache previously generated by the asynchronous `api_factory` to synchronously generate an api. The synchronous gactory will not introspect the database, only use the cache from a previous introspection. You can optionally call the helper `generate_couch_api` from the command line to generate a cache of your couchdb structure.
+The database can be introspected at runtime using the asynchronous `api_factory`. When this function is called, the database is introspected, an api is constructed, and a cache of the CouchDB structure is saved. The synchronous `api_factory_sync` can use a cache previously generated by the asynchronous `api_factory` to synchronously generate an api. The synchronous factory will not introspect the database, only use the cache from a previous introspection. You can optionally call the helper `generate_couch_api` from the command line to generate a cache of your couchdb structure.
#### Asynchronous factory ####
From within node call:
@@ -58,6 +58,7 @@ Once you have a cache, either from the command line or from a previous call to t
### 2. Use the API ###
There are four primary API methods, corresponding to the http methods:
+
* `get`
* `put`
* `post`
@@ -71,7 +72,7 @@ or against a particular handler:
couchdb.{{database_name}}
.{{design_doc_name}}
- .{{handler_name}}
+ .{{handler_name}}
.{{method}}
.{{http_method}}(options, callback)
@@ -134,6 +135,7 @@ When couchdb returns any code greater than 299, the api returns a javascript opt
<a name='factory_options' />
### Factory Options ###
The couchdb_factory, takes an optional options hash. If no hash is given, the defaults will be used. The defaults usually work just fine. However it is important to use `update` when the database structure has changed.
+
* `db_url` - the url to your CouchDB instance. It defaults to `http://127.0.0.1:5984`. If privileges are needed to view design documents or the root instance, provide username and password as: `http(s)://username:password@host_name`
* `admin` - basic auth string, `USERNAME:PASSWORD`, where `USERNAME` is an admin username and `PASSWORD` is the admin password, if you wish to be able to access admin-restricted content through the api. *The username and password will be stored in plain text in the cache.* See [options] reference(#options) for more.
* `file` is the location of the cached database configuration. YACA caches the database structure so it does not have to introspect the database every time it generates an api. If set to `false`, no cache will be created. Defaults to path/to/YACA/lib/api_cache.json.
@@ -149,6 +151,7 @@ YACA is derived from request, and so it supports most of the options supported b
Options can be either a string representing the command you wish to execute, or it can be an options object.
The valid keys in the options object are:
+
* `uri` || `url` - The CouchDB command you wish to execute. the API will prepend the appropriate url for the root/database/design doc/handler method from which you are making the request.
* `body` - entity body for POST and PUT requests. Must be buffer or string.
* `json` - sets `body` but to JSON representation of value and adds `Content-type: application/json` header.
@@ -161,7 +164,7 @@ The valid keys in the options object are:
### Standard API ###
-All of the following API calls conform are passed an options argument and a callback. The callback is then called with three arguments: an error, the CouchDB http response, and a javascript object parsed from the CouchDB response
+All of the following API calls are passed an options argument and a callback. The callback is then called with three arguments: an error, the CouchDB http response, and a javascript object parsed from the CouchDB response
#### CouchDB Root ####
* couchdb(options, callback) - shortcut for .get
@@ -177,7 +180,7 @@ All of the following API calls conform are passed an options argument and a call
* couchdb.{{db}}.put(options, callback)
* couchdb.{{db}}.del(options, callback)
-Where {{db}} is the name of the database. if your database name is a protected word, the YACA database_fatory will notify you, and {{db}} will be your database name prepended with '__' (two underscores).
+Where {{db}} is the name of the database. if your database name is a protected word, the YACA database factory will notify you, and {{db}} will be your database name prepended with '__' (two underscores).
#### Design Documents ####
* couchdb.{{db}}.{{ddoc}}(options, callback) - shortcut for .get
@@ -224,33 +227,33 @@ Anything you can do with the helper APIs you can do with the standard API. For e
, callback(e, r, b) {console.log(b)})
// response: {uuids: [{{uuid1}}, {{uuid2}}, {{uuid3}}]}
-As you can see, the helper functions simply reduce the verbosity. But if you are already familiar with the couchdb apis, it might simply be easier to use the standard API, rather than having to refer to the helper api.
+As you can see, the helper functions simply reduce the verbosity. If you are already familiar with the couchdb apis, it might be easier to use the standard API rather than having to refer to the helper api.
#### CouchDB Root ####
* couchdb._uuids([count], callback(error, uuids))
* `count` - number of uuids to return - defaults to 1
* `uuids` - array of uuid strings returned by CouchDB
-Returns `count` uuids retrieved from a call to _uuids.
+
+Returns an array of `count` uuids retrieved from a call to _uuids.
#### Database ####
* _new_doc(json, admin=false, callback(error, response, body))
* `json` - the document body as a javascript object.
* `admin` - whether to provide admin credentials for the operation
-Requests a uuid from the CouchDB server, puts the document described by `json` at that uuid. Returns the server response
+
+Requests a uuid from the CouchDB server, puts the document described by `json` at that uuid. Returns the server response.
+
* _delete(uuid, admin=false, callback(error, response, body))
* `uuid` - the uuid of the document to delete
* `admin` - whether to provide admin credentials for the operation
+
*Unsafe Deletion!* Deletes the object referenced by `uuid` without regard to version numbers.
-#### Updates ####
-* couchdb.{{db}}.{{ddoc}}.updates.{{method}}(json, callback)
- * `json` - body to send to the update
- * returns standard (error, response, body) to the callback
-
### Views ###
* couchdb.{{db}}.{{ddoc}}.views.{{method}}(query, callback)
* `query` - query parameters to pass to the view
- * returns standard (error, response, body) to the callback
+
+Returns standard (error, response, body) to the callback.

0 comments on commit 49d473c

Please sign in to comment.
Something went wrong with that request. Please try again.