PUT /{db}/{doc}

This request creates a new document or creates a new revision of an existing document. It enables you to specify the identifier for a new document rather than letting the software create an identifier. If you want to create a new document and let the software create an identifier, use the POST /db request.

If the document specified by doc does not exist, a new document is created and assigned the identifier specified in doc. If the document already exists, the document is updated with the JSON document in the message body and given a new revision.

Request

Request headers

• Accept—optional—Valid values are:

  • application/json
  • text/plain

• Content-Type—Required—Must be application/json.

• If-Match – Required for document updates if the rev query parameter is not supplied —Revision identifier of the requested document.

Query parameters

Response

Status codes

• 201 Created – Document created and stored on disk
• 202 Accepted – Document data accepted, but not yet stored on disk
• 400 Bad Request – Invalid request body or parameters
• 401 Unauthorized – Write privileges required
• 404 Not Found – Specified database or document ID doesn’t exist
• 409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document

Response headers

• Content-Type—The value can be:

  • application/json
  • text/plain; charset=utf-8

• ETag—Revision identifier enclosed in double quotes

Message body

The response is a JSON document that contains the following objects:

Example

The following example creates a new document with the identifier ButterChicken in a database named cookbook.

Request

PUT /cookbook/ButterChicken HTTP/1.1
Host: localhost:59840
Content-Type: application/json
{
    "description": "A very buttery chicken dish",
    "nutrition": "500 calories",
    "servings": 4,
    "title": "Butter Chicken"
}

Response

HTTP/1.1 201 Created
Accept-Ranges: bytes
Content-Length: 92
Content-Type: application/json
Date: Fri, 13 Dec 2013 19:34:04 GMT
Etag: "1-4101356e9c47d15d4f8f7390d05dbbcf"
Location: http://localhost:59840/cookbook/ButterChicken
Server: CouchbaseLite 1.486
{
  "id" : "ButterChicken",
  "rev" : "1-4101356e9c47d15d4f8f7390d05dbbcf",
  "ok" : true
}

The following example updates the document with the identifier ButterChicken that was created in the previous example. To update an existing document, the revision identifier of the current document must be supplied in an If-Match header or a rev query parameter. This example shows how to use both methods of specifying the revision.

Request

This form of the request uses the If-Match header to supply the revision identifier:

PUT /cookbook/ButterChicken HTTP/1.1
Host: localhost:59840
Content-Type: application/json
If-Match: 1-4101356e9c47d15d4f8f7390d05dbbcf
{
    "description": "A very buttery chicken dish",
    "nutrition": "500 calories",
    "serving-suggestion": "Serve with rice and green beans.",
    "servings": 4,
    "title": "Butter Chicken"
}

To use the rev query parameter rather than the If-Match header to supply the revision identifier, structure the request like this:

PUT /cookbook/ButterChicken?rev=1-4101356e9c47d15d4f8f7390d05dbbcf HTTP/1.1
Host: localhost:59840
Content-Type: application/json
{
    "description": "A very buttery chicken dish",
    "nutrition": "500 calories",
    "serving-suggestion": "Serve with rice and green beans.",
    "servings": 4,
    "title": "Butter Chicken"
}

Response

HTTP/1.1 201 Created
Accept-Ranges: bytes
Content-Length: 92
Content-Type: application/json
Date: Fri, 13 Dec 2013 19:56:09 GMT
Etag: "2-1b76d07281d4a576130c7d8f9f621d5e"
Location: http://localhost:59840/cookbook/ButterChicken
Server: CouchbaseLite 1.486
{
  "id" : "ButterChicken",
  "rev" : "2-1b76d07281d4a576130c7d8f9f621d5e",
  "ok" : true
}