1# Key: 2 3## Kivik components: 4 5- ![Kivik API](images/api.png) : Supported by the Kivik Client API 6- ![Kivik HTTP Server](images/http.png) : Supported by the Kivik HTTP Server 7- ![Kivik Test Suite](images/tests.png) : Supported by the Kivik test suite 8- ![CouchDB Logo](images/couchdb.png) : Supported by CouchDB backend 9- ![PouchDB Logo](images/pouchdb.png) : Supported by PouchDB backend 10- ![Memory Driver](images/memory.png) : Supported by Kivik Memory backend 11- ![Filesystem Driver](images/filesystem.png) : Supported by the Kivik Filesystem backend 12 13## API Functionality 14 15- ✅ Yes : This feature is fully supported 16- ☑️ Partial : This feature is partially supported 17- ⍻ Emulated : The feature does not exist in the native driver, but is emulated. 18- ? Untested : This feature has been implemented, but is not yet fully tested. 19- ⁿ/ₐ Not Applicable : This feature is supported, and doesn't make sense to emulate. 20- ❌ No : This feature is supported by the backend, but there are no plans to add support to Kivik 21 22<a name="authTable"> 23 24| Authentication Method | ![Kivik HTTP Server](images/http.png) | ![Kivik Test Suite](images/tests.png) | ![CouchDB](images/couchdb.png) | ![PouchDB](images/pouchdb.png) | ![Memory Driver](images/memory.png) | ![Filesystem Driver](images/filesystem.png) | 25|--------------|:-------------------------------------:|:-------------------------------------:|:------------------------------:|:------------------------------:|:-----------------------------------:|:------------------------------------------:| 26| HTTP Basic Auth | ✅ | ✅ | ✅ | ✅<sup>[1](#pouchDbAuth)</sup> | ⁿ/ₐ | ⁿ/ₐ<sup>[2](#fsAuth)</sup> 27| Cookie Auth | ✅ | ✅ | ✅<sup>[3](#couchGopherJSAuth)</sup> | | ⁿ/ₐ | ⁿ/ₐ<sup>[2](#fsAuth)</sup> 28| Proxy Auth | | | | | ⁿ/ₐ | ⁿ/ₐ<sup>[2](#fsAuth)</sup> 29 30### Notes 31 321. <a name="pouchDbAuth"> PouchDB Auth support is only for remote databases. Local databases rely on a same-origin policy. 332. <a name="fsAuth">The Filesystem driver depends on whatever standard filesystem permissions are implemented by your operating system. This means that you do have the option on a Unix filesystem, for instance, to set read/write permissions on a user/group level, and Kivik will naturally honor these, and report access denied errors as one would expect. 343. <a name="couchGopherJSAuth">Due to security limitations in the XMLHttpRequest spec, when compiling the standard CouchDB driver with GopherJS, CookieAuth will not work. 35 36| API Endpoint | ![Kivik API](images/api.png) | ![Kivik HTTP Server](images/http.png) | ![Kivik Test Suite](images/tests.png) | ![CouchDB](images/couchdb.png) | ![PouchDB](images/pouchdb.png) | ![Memory Driver](images/memory.png) | ![Filesystem Driver](images/filesystem.png) | 37|---------------------------------------|----------------------|:-------------------------------------:|:-------------------------------------:|:------------------------------:|:------------------------------:|:-----------------------------------:|:------------------------------------------:| 38| GET / | ServerInfo() | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 39| GET /_active_tasks | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 40| GET /_all_dbs | AllDBs() | ✅ | ✅ | ✅ | ☑️<sup>[1](#pouchAllDbs1),[2](#pouchAllDbs2),[3](pouchLocalOnly)</sup> | ✅ | ✅ 41| GET /_db_updates | DBUpdates() | | ✅ | ✅ | ⁿ/ₐ | 42| GET /_log | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 43| GET /_replicate | Replicate() | | ✅ | ✅<sup>[4](#replicator)</sup> | ✅ | 44| GET /_restart | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 45| GET /_stats | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 46| GET /_utils | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 47| GET /_uuids | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 48| GET /_membership | ⁿ/ₐ | ❌<sup>[12](#kivikCluster)</sup> | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ 49| GET /favicon.ico | ⁿ/ₐ | ✅ | ❌ | ❌ | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 50| POST /_session<sup>[6](#cookieAuth)</sup> | ⁿ/ₐ<sup>[13](#getSession)</sup> | ✅ | ✅ | ✅ | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 51| GET /_session<sup>[6](#cookieAuth)</sup> | Session() | ☑️ | ✅ | ✅ | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 52| DELETE /_session<sup>[6](#cookieAuth)</sup> | ⁿ/ₐ<sup>[13](#getSession)</sup> | ✅ | ✅ | ✅ | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 53| * /_config | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ | 54| HEAD /{db} | DBExists() | ✅ | ✅ | ✅ | ✅<sup>[5](#pouchDBExists)</sup> | ✅ | ✅ 55| GET /{db} | Stats() | ✅ | ✅ | ✅ | ✅ | | ☑️ 56| PUT /{db} | CreateDB() | ✅ | ✅ | ✅ | ✅<sup>[5](#pouchDBExists)</sup> | ✅ | ✅ 57| DELETE /{db} | DestroyDB() | | ✅ | ✅ | ✅<sup>[5](#pouchDBExists)</sup> | ✅ | ✅ 58| POST /{db} | CreateDoc() | | ✅ | ✅ | ✅ | ✅ | 59| (GET\|POST) /{db}/_all_docs | AllDocs() | | ☑️<sup>[7](#todoConflicts),[9](#todoOrdering),[10](#todoLimit)</sup> | ✅ | ? | ☑️<sup>[19](#memstatus)</sup> | 60| POST /{db}/_bulk_docs | BulkDocs() | | ✅ | ✅ | ✅ | ⍻ | | 61| POST /{db}/_find | Find() | | ✅ | ✅ | ✅ | 62| POST /{db}/_index | CreateIndex() | | ✅ | ✅ | ✅ | 63| GET /{db}/_index | GetIndexes() | | ✅ | ✅ | ✅ | 64| DELETE /{db}/_index | DeleteIndex() | | ✅ | ✅ | ✅ | 65| POST /{db}/_explain | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | | 66| (GET\|POST) /{db}/_changes | Changes()<sup>[8](#changesContinuous)</sup> | | ✅ | ✅ | ✅ | | | 67| POST /{db}/_compact | Compact() | | ✅ | ✅ | ✅ | | | 68| POST /{db}/_compact/{ddoc} | CompactView() | | | ✅ | ⁿ/ₐ | | | 69| POST /{db}/_ensure_full_commit | Flush() | ✅ | ✅ | ✅ | ⁿ/ₐ | ⁿ/ₐ | | 70| POST /{db}/_view_cleanup | ViewCleanup() | | ✅ | ✅ | ✅ | | | 71| GET /{db}/_security | Security() | | ✅ | ✅ | ⁿ/ₐ<sup>[14](#pouchPlugin)</sup> | ✅ 72| PUT /{db}/_security | SetSecurity() | | ✅ | ✅ | ⁿ/ₐ<sup>[14](#pouchPlugin)</sup> | ✅ 73| POST /{db}/_temp_view | ⁿ/ₐ | ⁿ/ₐ | ⁿ/ₐ| ⁿ/ₐ<sup>[16](#tempViews)</sup> | ⁿ/ₐ<sup>[17](#pouchTempViews)</sup> | ⁿ/ₐ | ⁿ/ₐ | 74| POST /{db}/_purge | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 75| POST /{db}/_missing_revs | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 76| POST /{db}/_revs_diff | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 77| GET /{db}/_revs_limit | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 78| PUT /{db}/_revs_limit | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 79| HEAD /{db}/{docid} | Rev() | | ✅ | ✅ | ⍻ | ⍻ 80| GET /{db}/{docid} | Get() | | ☑️<sup>[7](#todoConflicts),[11](#todoAttachments)</sup> | ✅ | ✅ | ☑️<sup>[18](#memstatus)</sup> 81| PUT /{db}/{docid} | Put() | | ☑️<sup>[11](#todoAttachments)</sup> | ✅ | ✅ | ☑️<sup>[18](#memstatus)</sup> 82| DELETE /{db}/{docid} | Delete() | | ✅ | ✅ | ✅ | ✅ 83| COPY /{db}/{docid} | Copy() | | ✅ | ✅ | ⍻ | 84| HEAD /{db}/{docid}/{attname} | GetAttachmentMeta() | | ✅ | ✅ | ⍻ | 85| GET /{db}/{docid}/{attname} | GetAttachment() | | ✅ | ✅ | ✅ | 86| PUT /{db}/{docid}/{attname} | PutAttachment() | | ✅ | ✅ | ✅ | 87| DELETE /{db}/{docid}/{attname} | DeleteAttachment() | | ✅ | ✅ | ✅ | 88| HEAD /{db}/_design/{ddoc} | Rev() | | ✅ | ✅ | ✅ | 89| GET /{db}/_design/{ddoc} | Get() | | ✅ | ✅ | ✅ | 90| PUT /{db}/_design/{ddoc} | Put() | | ✅ | ✅ | ✅ | 91| DELETE /{db}/_design/{ddoc} | Delete() | | ✅ | ✅ | ✅ | 92| COPY /{db}/_design/{ddoc} | Copy() | | ✅ | ✅ | ⍻ | 93| HEAD /{db}/_design/{ddoc}/{attname} | GetAttachmentMeta() | | ✅ | ✅ | ✅ | 94| GET /{db}/_design/{ddoc}/{attname} | GetAttachment() | | ✅ | ✅ | ✅ | 95| PUT /{db}/_design/{ddoc}/{attname} | PutAttachment() | | ✅ | ✅ | ✅ | 96| DELETE /{db}/_design/{ddoc}/{attname} | DeleteAttachment() | | ✅ | ✅ | ✅ | 97| GET /{db}/_design/{ddoc}/_info | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 98| (GET\|POST) /{db}/_design/{ddoc}/_view/{view} | Query() | | ✅ | ✅ | ✅<sup>[18](#pouchViews)</sup> | 99| GET /{db}/_design/{ddoc}/_show/{func} | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 100| POST /{db}/_design/{ddoc}/_show/{func} | ⁿ/ₐ| | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 101| GET /{db}/_design/{ddoc}/_show/{func}/{docid} |ⁿ/ₐ| | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 102| POST /{db}/_design/{ddoc}/_show/{func}/{docid} |ⁿ/ₐ| | |❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 103| GET /{db}/_design/{ddoc}/_list/{func}/{view} | ⁿ/ₐ| | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 104| POST /{db}/_design/{ddoc}/_list/{func}/{view} |ⁿ/ₐ| | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 105| GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view} |ⁿ/ₐ| | |❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 106| POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view} |ⁿ/ₐ| | |❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 107| POST /{db}/_design/{ddoc}/_update/{func} | ⁿ/ₐ | | |❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 108| PUT /{db}/_design/{ddoc}/_update/{func}/{docid} |ⁿ/ₐ| | |❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 109| ANY /{db}/_design/{ddoc}/_rewrite/{path} | ⁿ/ₐ | | | ❌<sup>[15](#notPublic)</sup> | ⁿ/ₐ | 110| HEAD /{db}/_local/{docid} | Rev() | | ✅ | ✅ | ✅ | 111| GET /{db}/_local/{docid} | Get() | | ✅ | ✅ | ✅ | 112| PUT /{db}/_local/{docid} | Put() | | ✅ | ✅ | ✅ | 113| DELETE /{db}/_local/{docid} | Delete() | | ✅ | ✅ | ✅ | 114| COPY /{db}/_local/{docid} | Copy() | | ✅ | ✅ | ⍻ | 115 116### Notes 117 1181. <a name="pouchAllDbs1"> PouchDB support for AllDbs depends on the 119 [pouchdb-all-dbs plugin](https://github.com/nolanlawson/pouchdb-all-dbs). 1202. <a name="pouchAllDbs2"> Unit tests broken in PouchDB due to an [apparent 121 bug](https://github.com/nolanlawson/pouchdb-all-dbs/issues/25) in the 122 pouchdb-all-dbs plugin. 1233. <a name="pouchLocalOnly"> Supported for local PouchDB databases only. A work 124 around may be possible in the future for remote databases. 1254. <a name="replicator"> Replications are actually done via the _replicator 126 database, not the /_replicate endpoint. 1275. <a name="pouchDBExists"> PouchDB offers no way to check for the existence of 128 a local database without creating it, so `DBExists()` always returns true, 129 `CreateDB()` does not return an error if the database already existed, and 130 `DestroyDB()` does not return an error if the database does not exist. 1316. <a name="cookieAuth"> See the CookieAuth section in the [Authentication methods table](#authTable) 1327. <a name="todoConflicts"> **TODO:** Conflicts are not yet tested. 1338. <a name="changesContinuous"> Changes feed operates in continuous mode only. 1349. <a name="todoOrdering"> **TODO:** Ordering is not yet tested. 13510. <a name="todoLimit"> **TODO:** Limits are not yet tested. 13611. <a name="todoAttachments"> **TODO:** Attachments are not yet tested. 13712. <a name="kivikCluster"> There are no plans at present to support clustering. 13813. <a name="getSession"> Used for authentication, but not exposed directly to 139 the client API. 14014. <a name="pouchPlugin"> This feature is not available in the core PouchDB 141 package. Support is provided in PouchDB plugins, so including optional 142 support here may be possiblein the future. 14315. <a name="notPublic"> This feature is not considered (by me, if nobody else) 144 part of the public CouchDB API, or otherwise not meaningful to make part of 145 the Kivik API, so there are no (immediate) plans to implement support. If 146 you feel this should change for a given feature, please create an issue and 147 explain your reasons. 14816. <a name="tempViews"> As of CouchDB 2.0, temp views are no longer supported, 149 so I see no reason to support them in this library for older server versions. 150 If you feel they should be supported, please create an issue and make your 151 case. 15217. <a name="pouchTempViews"> At present, PouchDB effectively supports temp 153 views by calling [query](https://pouchdb.com/api.html#query_database) with 154 a JS function. This feature is scheduled for removal from PouchDB (into a 155 plugin), but until then, this functionality can still be used via the 156 Query() method, by passing a JS function as an option. 15718. <a name="pouchViews"> Only queries against defined design documents are 158 supported. That is to say, providing raw JS functions is not supported. If 159 you need this, please create an issue to make your case. 16019. <a name="memstatus"> See [Issue #142](https://github.com/go-kivik/kivik/issues/142) 161 for the current status of the memory driver. 162 163## HTTP Status Codes 164 165The CouchDB API prescribes some status codes which, to me, don't make a lot of 166sense. This is particularly true of a few error status codes. It seems the folks 167at [Cloudant](https://cloudant.com/) share my opinion, as they have changed some 168as well. 169 170In particular, the CouchDB API returns a status 500 **Internal Server Error** for 171quite a number of malformed requests. Example: `/_uuids?count=-1` will return 172500. Cloudant and Kivik both return 400 **Bad Request** in this case, and in 173many other cases as well, as this seems to better reflect the actual state. 174