The add POST/PUT request requires a JSON with the fields:
- key: The unique identifier of the content record. Keys will be saved with a zone prefix. If the prefix is not specified, the local zone prefix will be added automatically. Because of the prefix, a key cannot contain colon (:) characters as it is used as the prefix separator.
- version: A version to chronologically identify the transaction. If a record with key already exists with a higher version, the request will be discarded.
- content: JSON content associated with the scope being added. Content will be saved encrypted and compressed if specified on the storage unit configuration.
- policy: The policy to use when adding a new content record:
- new: only adds the content if the key doesn't exist in the storage unit.
- overwrite: if a record with key already exists, it overwrites all of it's previous content (discards other existing scopes for that key), otherwise, it adds the record.
- merge: if a record with key already exists, it adds the scope information without affecting any other scopes for this record.
PUT transaction/add/<storage-unit-name>/<scope> { "content": {"doc": {"test":"value"}}, "policy": "merge", "key": "LOCAL_ZONE:B166F75594BF1B23A26A6F0074BEB88F", "version": 1445618448043 }
Response
If the add operation is successful, a 200 response code and an OK message are returned.
{"message":"OK"}
Execute
Executes a JSON transaction against the storage unit.
Request
The URL is composed by the Storage Unit and the scope (I.e. connector, ocr, index, etc) to which the key content will be saved to. Note: scope is required if the action is add/update, for other actions it is optional.
The execute POST/PUT request requires a JSON with the fields::
- key: The unique identifier of the content record. Keys will be saved with a zone prefix. If the prefix is not specified, the local zone prefix will be added automatically. Because of the prefix, a key cannot contain colon (:) characters as it is used as the prefix separator.
- version: A version to chronologically identify the transaction. If a record with key already exists with a higher version, the request will be discarded.
- content: When the action is add/update, it is JSON content to store. Content will be saved encrypted and compressed if specified on the storage unit configuration.
- action: The transaction type to execute on the record's scope: add, update, delete. Custom transaction types can be specified in this field to trigger custom document and general events as described in here.
- policy: The policy to use when executing the action on the content record:
- add/update actions
- new: only adds the content if the key doesn't exist in the storage unit.
- overwrite: if a record with key already exists, it overwrites all of it's previous content (discards other existing scopes for that key), otherwise, it adds the record.
- merge: if a record with key already exists, it adds the scope information without affecting any other scopes for this record.
- delete actions:
- silent: If the record/scope for key doesn't exist, the request completes without an error.
- mustexist: If the record/scope for key doesn't exist, an error is reported back in the response.
- custom actions: policy is not required in these cases.
- add/update actions
PUT transaction/execute/<storage-unit-name>/<scope> { "content": {"doc": {"test":"value"}}, "action": "add", "policy": "merge", "key": "LOCAL_ZONE:B166F75594BF1B23A26A6F0074BEB88F", "version": 1445618448043 }
Response
If the execute operation is successful, a 200 response code and an OK message are returned.
{"message":"OK"}
Batch
Executes a list of JSON transactions against the storage unit. The batch expects a list of single line JSON strings.
Request
The URL is composed by the Storage Unit and the scope (I.e. connector, ocr, index, etc) against which all transactions will be executed to.
The batch POST/PUT request requires a list of JSON objects separated by a new line, each with:
- key: The unique identifier of the content record. Keys will be saved with a zone prefix. If the prefix is not specified, the local zone prefix will be added automatically. Because of the prefix, a key cannot contain colon (:) characters as it is used as the prefix separator.
- version: A version to chronologically identify the transaction. If a record with key already exists with a higher version, the request will be discarded.
- content: When the action is add/update, it is JSON content to store. Content will be saved encrypted and compressed if specified on the storage unit configuration.
- action: The transaction type to execute on the record's scope: add, update, delete. Custom transaction types can be specified in this field to trigger custom document and general events as described in here.
- policy: The policy to use when executing the action on the content record:
- add/update actions
- new: only adds the content if the key doesn't exist in the storage unit.
- overwrite: if a record with key already exists, it overwrites all of it's previous content (discards other existing scopes for that key), otherwise, it adds the record.
- merge: if a record with key already exists, it adds the scope information without affecting any other scopes for this record.
- silent: If the record/scope for key doesn't exist, the request completes without an error.
- mustexist: If the record/scope for key doesn't exist, an error is reported back in the response.
- custom actions: policy is not required in these cases.
- add/update actions
An optional report parameter can be specified to get processing statistics and error reports.
POST transaction/batch/<storage-unit-name>/<scope>?report {"content": {"doc": {"test":"value"}},"action": "add", "policy": "merge", "key": "LOCAL_ZONE:B166F75594BF1B23A26A6F0074BEB88F", "version": 1445618448043} {"content": {"doc": {"test":"value2"}}, "action": "delete", "policy": "silent", "key": "EXTERNAL_ZONE:B6F5H6J8HGBF1B23A26A6F0074BEB8E5", "version": 1445618448133}
Response
If the batch operation is successful, a 200 response code and an OK message are returned if no transactions failed. A COMPLETED_WITH_ERRORS message if one or more transactions failed.
When it completes successfully:
{"message":"OK"}
When it completes with errors:
{"message":"COMPLETED_WITH_ERRORS"}
If the report parameter is specified, a 200 response code is returned with the list of processed keys and a status for each key, as well as a general report. An OK message value if no errors occurred or COMPLETED_WITH_ERRORS with one or more transactions failed.
When it completes successfully:
{"message":"OK"}
When it completes with errors:
{ "message": "COMPLETED_WITH_ERRORS", "errors": [ { "key": "APP_ZONE:batch1", "error": "NEW_MERGE_POLICY_ERROR" }, { "key": "APP_ZONE:batch3", "error": "NEWER_VERSION_ALREADY_EXISTS" } ] }
Delete
Deletes a scope or all scopes for a key in the specified storage unit.
Request
The URL is composed by the Storage Unit and the scope (I.e. connector, ocr, index, etc.) to delete from the record. If scope = $record or the scope is not provided, the whole record will be deleted.
The delete POST/DELETE request requires a JSON with the fields::
- key: The unique identifier of the content record. If the zone is not specified, the key that matches the local zone will be deleted.
- version: A version to chronologically identify the transaction. If a record with key already exists with a higher version, the request will be discarded.
- policy: The policy to use when deleting a scope of the record:
- silent (default): If the record/scope doesn't exist, the request completes without an error.
- mustexist: If the record/scope doesn't exist, an error is reported back in the response.
DELETE transaction/delete/<storage-unit-name>/<optional:scope> { "policy": "silent", //delete: silent, mustexist "key": "B6F5H6J8HGBF1B23A26A6F0074BEB8E5", "version": 1445618448133 }
Response
If the delete operation is successful, a 200 response code and an OK message are returned.
{"message":"OK"}
If the storage unit doesn't exist, a 400 response code with a STORAGE_UNIT_DOESNT_EXIST message is returned.
{"message": "STORAGE_UNIT_DOESNT_EXIST"}
If the scope doesn't exist and the delete policy was MUSTEXIST, a 400 response code with a DELETED_SCOPE_DOESNT_EXIST message is returned.
{"message": "DELETED_SCOPE_DOESNT_EXIST"}
Delete All
Deletes the provided scope for all content records of the storage unit. If the scope is the global $record scope or it is not provided, all content records are deleted.
Request
The URL is composed by the Storage Unit and the scope (I.e. connector, ocr, index, etc.) to delete from the record. If scope = $record, the whole record will be deleted.
The delete all POST/DELETE request requires a JSON with the fields::
- version: A version to chronologically identify the transactions. If a record with key already exists with a higher version, the key will not be deleted.
- zone: Optional. If specified, it will delete all items with a higher version than version that are of the specified zone only.
DELETE transaction/deleteAll/<storage-unit-name>/<optional:scope> { "version": 1445618448133 "zone": "LOCAL_ZONE" }
Response
If the delete all operation is successful, a 200 response code and an OK message are returned.
{"message":"OK"}
If the storage unit doesn't exist, a 400 response code with a STORAGE_UNIT_DOESNT_EXIST message is returned.
{"message": "STORAGE_UNIT_DOESNT_EXIST"}
Delete If
Deletes a content record scope based on a comparison criteria (X field is equal (EQ), greater than (GT), lesser than (LT) or not equal (NEQ) to a value).
Request
The URL is composed by the Storage Unit and the scope (I.e. connector, ocr, index, etc.) to delete from the record.
The delete if POST/DELETE request requires a JSON with the fields::
- version: A version to chronologically identify the transactions. If a record with key already exists with a higher version, the key will not be deleted.
- policy: The policy to use when deleting the scope of the records:
- silent (default): If the record/scope doesn't exist, the request completes without an error.
- mustexist: If the record/scope doesn't exist, an error is reported back in the response for the record.
- xpath: An xpath in the scope's JSON object for the field to evaluate.
- test: The comparison operation to perform on the value of the field found by the xpath.
- value: The value to compare against the value of the field found by the xpath.
- scopeToDelete: The scope to delete in the record if the criteria is met. If scope to delete is not provided, the scope deleted is the same as the scope specified on the URL.
- zone: Specific zone to scan records in. If not specified, local zone will be scanned for deletes.
DELETE transaction/deleteIf/<storage-unit-name>/<scope> { "version": 1445618448133, "policy": "silent", "test": "EQ", "xpath": "/url", "value": "E:\\LSA\\Foundations_of_Statistical_Natural_Language_Processing.pdf", "scopeToDelete": "index" }
Response
Returns a 200 response code with the statusId to be used by the DeleteIfStatus API call.
{"statusId": "id"}
If the storage unit doesn't exist, a 400 response code with a STORAGE_UNIT_DOESNT_EXIST message is returned.
{"message": "STORAGE_UNIT_DOESNT_EXIST"}
Delete If Status
Returns the current status of the delete if processing execution for the storage unit.
Request
The delete if status GET request will return a JSON with the current status of the deleteif processing that has been previously executed.
GET transaction/deleteIfStatus/id
Response
A 200 response code is received and the current status with the number of deleted items and/or errors.
{"message":{"status":"complete","deleteCount":1}}
Put File
Uploads a file to a file specific scope of a specific record. Files can only be uploaded to scopes that don't previously exist, or that already contain files. Put file uses multipart/form-data format to upload the file. Metadata associated with the file can also be specified as multipart/form-data fields.
Request
The put file PUT/POST multipart/form-data request URL requires the storageunit, record key and the scope where the file will be uploaded. The request multipart/form-data body requires at least a file field with the file reference. By default the version for the file will be set to 1 and the policy will be merge (same policies as the add action policies). To specify additional metadata for the file, add other multipart/form-data text fields to the request.
PUT transaction/putFile/<storage-unit>/<key>/<scope>
Headers:
- Content-type: multipart/form-data;boundary=BOUNDARY_TOKEN
Body:
- file: File type field where the file is specified. The filename will be used as the file identifier when requesting back the file.
- version: A version to chronologically identify the file transactions. If a file with the same filename already exists with a higher version, the filename will not be added.
- policy: The policy to use when adding a file:
- new: only adds the file doesn't exist in the scope.
- overwrite: if a file with the same name already exists, it overwrites all of it's previous metadata and updates the file.
- merge: if a file with the same name already exists, it adds any new metadata to the file metadata, overwrites existing metadata for that file.
- additional metadata: any other field in the request will be considered file metadata and saved as such. The field name can have the filename as a prefix, separated by a colon.
Response
If the file is uploaded correctly, a 200 response code and an OK message are returned.
{"message":"OK"}
Multiple File Upload
Using the same putFile request, multiple files can be uploaded at once to the same scope of a storage unit.
To upload multiple files, the multpart/form-data request accepts multiple entries of the file field.
To specify metadata specific to a file, add the file name as a prefix to the metadata fields for that file, including version and policy. If a prefix is not specified, the field is considered general and it is added as metadata for all files.
Body Sample:
field | value |
---|---|
file | file1.jpg |
file | file2.jpg |
file1.jpg:version | 1 |
file2.jpg:version | 4 |
policy | merge |
file1.jpg:title | logo |
description | Logo image |
In this example, two files will be added:
- file1.jpg:
- version = 1
- policy = merge
- title = logo
- description = Logo image
- file2.jpg (no title field)
- version = 4
- policy = merge
- description = Logo image
Delete File
Deletes a file, given the file name, from a file scope of the specified record.
Request
The delete file DELETE/POST request requires the storage unit name, record key, scope name and the file name to delete. Additionally requires a JSON body with a version and delete policy.
- version: A version to chronologically identify the file transactions. If a file within record with the same file name already exists with a higher version, the file will not be deleted.
- policy: The policy to use when deleting the file from the scope of the record:
- silent (default): If the file doesn't exist in the record's scope, the request completes without an error.
- mustexist: If the file doesn't exist in the record's scope, an error is reported back in the response for the record.
PUT transaction/deleteFile/<storage-unit>/<key>/<scope>/<filename> { "version":5, "policy":"silent" }
Response
If the file is deleted correctly, a 200 response code and an OK message are returned.
{"message":"OK"}