documents/batch JSON API

The body of a documents/batch request uses SDF to specify the document operations you want to perform. An SDF JSON representation of a batch is a collection of objects that define individual add and delete operations. The type property identifies whether an object represents an add or delete operation. For example, the following JSON SDF batch adds one document and deletes one document:

[
{ "type": "add",
  "id":   "tt0484562",
  "version": 1,
  "lang": "en",
  "fields": {
    "title": "The Seeker: The Dark Is Rising",
    "director": "Cunningham, David L.",
    "genre": ["Adventure","Drama","Fantasy","Thriller"],
    "actor": ["McShane, Ian","Eccleston, Christopher","Conroy, Frances",
              "Crewson, Wendy","Ludwig, Alexander","Cosmo, James",
              "Warner, Amelia","Hickey, John Benjamin","Piddock, Jim",
              "Lockhart, Emma"]
  }
},
{ "type": "delete",
  "id":   "tt0484575",
  "version": 2
  }]

An add or delete operation is only applied to an existing document if the version number specified in the operation is greater than the existing document's version number. If a batch contains multiple add or delete operations for the same document, the operation with the highest version number is applied. (If multiple operations in a batch specify the same document and version number, the document service arbitrarily picks which one to apply.)

The JSON schema representation of a batch is shown below:

{
    "type": "array",
    "minItems": 1,
    "items": {
        "type": "object",
        "properties": {
            "type": {
                "type": "string",
                "enum": ["add", "delete"],
                "required": true
            },
            "id": {
                "type": "string",
                "pattern": "[a-z0-9][a-z0-9_]{0,127}",
                "minLength": 1,
                "maxLength": 128,
                "required": true
            },
            "version": {
                "type": "number",
                "minimum": 1,
                "maximum": 4294967295
                "required": true
            },
            "lang": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2
            },
            "fields": {
                "type": "object",
                "patternProperties": {
                    "[a-zA-Z0-9][a-zA-Z0-9_]{0,63}": {
                        "type": "string",
                    }
                }
            }
        }
    }
}

"genre": ["Adventure","Drama","Fantasy","Thriller"]

The response body lists the number of adds and deletes that were performed and any errors or warnings that were generated.

The JSON schema representation of a document service API response is shown below:

{
    "type": "object",
    "properties": {
        "status": {
            "type": "text",
            "enum": ["success", "error"],
            "required": true
        },
        "adds": {
            "type": "integer",
            "minimum": 0,
            "required": true
        },
        "deletes": {
            "type": "integer",
            "minimum": 0,
            "required": true
        },
        "errors": {
            "type": "array",
            "required": false,
            "items": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "required": true
                    }
                }
            }
        },
        "warnings": {
            "type": "array",
            "required": false,
            "items": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "required": true
                    }
                }
            }
        }
    }
}