CouchDB - Curl & Futon

CouchDB - Interacting with the API

CouchDB is built on a RESTful HTTP API, meaning you can interact with it using standard HTTP methods. There are three primary ways to do this: using a command-line tool like cURL, the web-based interface Fauxton, or an application-level SDK.

1. Interacting via Command Line (cURL)

cURL is a powerful command-line tool for making HTTP requests. It’s excellent for scripting, testing, and quick interactions. The most common flags you will use with CouchDB are:

• -X <METHOD>: Specifies the HTTP method, e.g., GET, POST, PUT, DELETE.
• -H <HEADER>: Sets a request header, e.g., -H 'Content-Type: application/json'.
• -d <DATA>: Sends data in the request body, e.g., a JSON object.
• -u <user:password>: Provides credentials for Basic HTTP Authentication.

Example: Checking the CouchDB Status

You can send a GET request to the root of your CouchDB instance to verify it’s running and get basic information.

$ curl -X GET http://127.0.0.1:5984/ -u admin:secret

{
  "couchdb": "Welcome",
  "version": "3.3.2",
  "git_sha": "...",
  "uuid": "...",
  "features": [
    "partitioned",
    "reshard",
    "scheduler"
  ],
  "vendor": {
    "name": "The Apache Software Foundation"
  }
}

This response confirms the server is running and provides version details. Note that the exact version, git_sha, and uuid will differ based on your installation.

2. Interacting via Web Interface (Fauxton)

Fauxton is the modern, official web UI for CouchDB (2.0+), replacing the legacy tool Futon. It is the most user-friendly way to manage your CouchDB instance.

You can access Fauxton by navigating to http://127.0.0.1:5984/_utils/.

Key features of Fauxton include:

• Database Management: Create, view, and delete databases.
• Document Management: A full-featured JSON editor for creating, reading, updating, and deleting documents (CRUD).
• Querying and Indexing: A built-in interface to create and run Mango queries, and to manage MapReduce views.
• Replication: A visual tool to set up, monitor, and manage replications between databases.
• System Status: View active tasks, logs, and configuration settings.

For most day-to-day administrative tasks, Fauxton provides a powerful and intuitive graphical interface.

3. Interacting via Application Code (SDKs)

When building an application, directly making cURL or HTTP calls is cumbersome and error-prone. The best practice is to use a language-specific Software Development Kit (SDK) or client library. These libraries provide a convenient abstraction over the HTTP API.

Benefits of using an SDK include:

• Cleaner, more readable code.
• Proper handling of connections and authentication.
• Helper functions for common operations (e.g., creating documents, fetching views).
• Better error handling and type safety (in typed languages).

Conceptual Example: Node.js with nano

Here is a conceptual code snippet showing how to create a database and a document using nano, the official Node.js library for CouchDB. This demonstrates how much simpler the code becomes.

// To run this, you need Node.js and the 'nano' package.
// Setup: npm init -y && npm install nano

const nano = require('nano')('http://admin:secret@127.0.0.1:5984');

async function initializeAppDb() {
  const dbName = 'my-app-db';

  try {
    // Create the database (ignores error if it already exists)
    await nano.db.create(dbName);
    console.log(`Database '${dbName}' created or already exists.`);

    // Select the database to use
    const db = nano.use(dbName);

    // Create a new document
    const userProfile = {
      type: 'user',
      name: 'Alice Wonder',
      email: 'alice.wonder@example.com'
    };
    const response = await db.insert(userProfile);

    console.log('Document created successfully:', response);

  } catch (error) {
    console.error('An error occurred:', error.message);
  }
}

initializeAppDb();

This approach is more robust, maintainable, and scalable for any real-world application.