Skip to content

Update a document

PUT /api/document/{documentId}

Update an existing Formbird document

Arguments

  • your apiKey, for example: bf5b0500-9332-11e6-9c03-853f647fe4a4

  • documentId

  • a document change, for example:

json { "text": "apiTest2" }

Example Request
curl http://localhost:3000/api/document/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6 \
 -X PUT \
 -H "Content-Type: application/json;charset=UTF-8" \
 -H "apiKey: bf5b0500-9332-11e6-9c03-853f647fe4a4" \
 -d "{\"text\": \"apiTest2\"}"
Example Response
{
    "systemHeader": {
        "templateId": "547fe84c9c1d86680d9806bd",
        "keyIds": [],
        "serverUpdatedDate": "2017-09-08T03:20:12.299Z",
        "serverCreatedDate": "2017-09-08T03:20:12.299Z",
        "versionId": "a01d4810-9444-11e7-a6b2-d9cc8e84f3a6",
        "excludeGeneralSearch": false,
        "systemType": "document",
        "currentVersion": true,
        "createdDate": "2017-09-08T03:20:12.305Z",
        "createdBy": "548684a629a5e8d820b12c01",
        "summaryName": "apiTest2",
        "summaryDescription": "apiTest2",
        "previousVersionId": "de24de40-9442-11e7-a6b2-d9cc8e84f3a6"
    },
    "text": "apiTest2",
    "documentId": "dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6"
}

The response contains the updated document

Using JSONPatch

JSON Patch is a format for specifying partial updates to a JSON document. It allows clients to send a list of operations to be applied to the target JSON document on the server. These operations are expressed as a JSON array, where each element of the array represents a single patch operation. JSON Patch uses a minimal set of operations, making it simple and efficient to apply changes to JSON documents.

JSON Patch Operations

The following are the primary JSON Patch operations:

  • add: Adds a new value at a specified location.
  • remove: Removes the value at a specified location.
  • replace: Replaces the value at a specified location.
  • move: Moves a value from one location to another.
  • copy: Copies a value from one location to another.
  • test: Tests that a value at a specified location matches a specified value.

Example document:

{
  "baz": "qux",
  "foo": "bar"
}

Example patch:

[
  { "op": "replace", "path": "/baz", "value": "boo" },
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo" }
]

The result:

{
  "baz": "boo",
  "hello": ["world"]
}

To know more about jsonpatch you can check https://jsonpatch.com.

Updating a document usng JSONpatch

With JSON Patch, you can efficiently update a document without sending the entire content. Only the changes in JSON Patch format and the document's patched versionId are required. You should include the patchedVersionId and the updates under the options object in the request data.

PUT /api/document/deepDiffUpdate/{documentId}

Example Request
curl http://localhost:3000/api/document/deepDiffUpdate/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6 \
 -X PUT \
 -H "Content-Type: application/json;charset=UTF-8" \
 -H "apiKey: bf5b0500-9332-11e6-9c03-853f647fe4a4" \
 -d "{\"options\": { \"patchedVersionId\": \"f8642b68-5b12-44f9-a690-865aa1c2008e\"}, \"updates\": [ {\"op\":\"replace\",\"path\":\"/field\",\"value\":\"value update\"} ] }"

Auto-Generating JSONPatch with Libraries

Modern programming environments offer libraries that can automatically generate a JSONPatch by comparing an original and an updated JSON document. This feature simplifies the process of creating a JSONPatch, as it allows developers to focus on the changes they wish to apply, rather than the mechanics of patch creation. Below are examples of such libraries in Java, Python, and Node.js.

Java

In Java, you can use the zjsonpatch library to generate JSONPatch.

Example:

import com.flipkart.zjsonpatch.JsonDiff;

public class JsonPatchExample {
    public static void main(String[] args) {
        String originalJson = "{\"baz\":\"qux\",\"foo\":\"bar\"}";
        String updatedJson = "{\"baz\":\"boo\",\"hello\":[\"world\"]}";

        JsonNode patch = JsonDiff.asJson(mapper.readTree(originalJson), mapper.readTree(updatedJson));
        System.out.println(patch.toString());
    }
}

Python

For Python, the jsonpatch library can be used.

Example:

import jsonpatch
import json

original = json.loads('{"baz": "qux", "foo": "bar"}')
updated = json.loads('{"baz": "boo", "hello": ["world"]}')

patch = jsonpatch.make_patch(original, updated)
print(patch.to_string())

Node.js

In Node.js, the fast-json-patch package is commonly used.

Example:

const jsonpatch = require('fast-json-patch');

const originalDocument = { baz: "qux", foo: "bar" };
const updatedDocument = { baz: "boo", hello: ["world"] };

const patch = jsonpatch.compare(originalDocument, updatedDocument);
console.log(JSON.stringify(patch));