Description

There are two ways to save a document - with an defined schema, or without one. Users wanting more flexibility and control over files and security should create documents with a schema.

Note that “schema-less” documents are actually documents with a default schema. This default schema contains the field "apsdb_attachments" that can be used to attach a file to the schema-less document.

Creating Documents

To create a document, users should create fields that make up this document. Creating a field can be done by providing [fieldname]=[fieldValue] pairs and setting the apsdb.multivalueAppend parameter=[fieldname] to append multiple values else the last value of the fieldname will be set only.

When specifying fields, users can send a fieldType. This will ensure the field value will be parsed and validated. The fieldType defaults to "string" if not sent. Any other values than the predefined types (string, text, numeric, date, file, geospatial) are not allowed.

Note that all fieldNames starting with apsdb or ending with apsdb.fieldType or apsdb.fieldDateFormat cannot be sent more than once, else an error (DUPLICATE_PARAMETER_VALUE) will be returned.

When saving a document, it should be specified to what store it is saving. When saving a document, users can send a document key. If the key is not sent, then apstrata database will generate a store-bound unique id, called a document key, for each document. This key will be used when updating the document later.

Please remember that apstrata database uses the document key to index its documents, so it is necessary to have random document keys. More importantly, the first few letters of the document key should be random and unique. The reason for random document keys is to optimize the indexing process and make your data storage and retrieval operations faster. For example:

Good document keys:

123_john, 234_john, 345_john, 456_john, …

Bad document keys:

john_123, john_234, john_345, john_456, …

Field of type 'date':
When saving a field of type 'date', the system needs to know the format used to parse the date sent in the request. There are three ways to do so:

1- Use the default system format:
The system accepts two date formats by default:
yyyy-MM-dd'T'HH:mm:ssZ (e.g. 2012-04-13T13:01:02+0000)
yyyy-MM-dd (e.g. 2012-04-13)
Unless otherwise specified, the fields of type 'date' sent in the SaveDocument request will be expected to use one of the two default formats and will be parsed accordingly.
An error is returned if the date does not match either of these formats.
Below is an example of a javascript implementation that generates a date in the default system format:
new Date().toISOString().split(".")[0]+"+0000"

2- Use the apsdb.globalDateFormat request parameter:
Sending the apsdb.globalDateFormat parameter in the SaveDocument request informs the system to expect all 'date' fields of the current document to use the specified format. The dates will be parsed using this new format and an error will be returned if one of the fields cannot be parsed.
The format specified in the apsdb.globalDateFormat parameter always overrides the default system date format for the current document.

3- Use the [fieldName].apsdb.fieldDateFormat request parameter:
Sending a date format in the [fieldName].apsdb.fieldDateFormat parameter informs the system that the value of field [fieldName] uses the specified format and should be parsed accordingly. If the format of the date sent in this field is not the one specified in the parameter then an error will be returned.
The format specified in the [fieldName].apsdb.fieldDateFormat parameter always overrides both the default system date format and the format sent in the apsdb.globalDateFormat parameter for the specified field ([fieldName]).

Please note that the server time is GMT.

Field of type 'file':

Saving a field of type "file" is done differently if the document is bound to a schema or not.

1- Document is schemaless:
Only the special field "apsdb_attachments" can be used to save a file to a document that is not bound to a schema. It is possible to attach multiple files to the "apsdb_attachments" field by sending its name in the apsdb.multivalueAppend parameter (ex:  apsdb.multivalueAppend=apsdb_attachments).
If a user sends a file in a different field than “apsdb_attachments”, an error will occur with code "INVALID_FIELD_VALUE".

2- Document is bound to a schema:
If the document being saved is bound to a schema then files can only be saved under fields of type "file" defined in the schema. Trying to save a file under a field that is not defined in the schema or under the special field "apsdb_attachments" will result in an error with code "FIELD_FILE_NOT_DEFINED".

To save a file to a document, you need to send it in a multipart request. This can either be done in an HTML form with an input of type “file” representing the field under which the file will be saved (ex: <input type=”file” name=”myFileFieldName”>) or by sending a raw HTTP request as follows:

POST /apsdb/rest/[authenticationkey]/SaveDocument?apsws.time=1245681044 &apsws.authSig=5cf178fed074ec9dfa202627d860123f0e7daf0f HTTP/1.0
Host: sandbox.apstrata.com
Content-Type: multipart/form-data; boundary=---------------------e7b6ef072f
Content-length: 1516
-----------------------e7b6ef072f
Content-Disposition: form-data; name="apsdb.documentKey"
documentKey
-----------------------e7b6ef072f
Content-Disposition: form-data; name="apsdb.store"
myStore
-----------------------e7b6ef072f
Content-Disposition: form-data; name="newNumericField4"
1200
-----------------------e7b6ef072f
Content-Disposition: form-data; name="newNumericField4"
1100
-----------------------e7b6ef072f
Content-Disposition: form-data; name="newNumericField4.apsdb.fieldType"
numeric
-----------------------e7b6ef072f
Content-Disposition: form-data; name="field1"
myField1
-----------------------e7b6ef072f
Content-Disposition: form-data; name="field1.apsdb.fieldType"
string
-----------------------e7b6ef072f
Content-Disposition: form-data; name="apsdb_attachments"; filename="myFile.txt"
Content-Type: application/octet-stream
my
 file contents, my file contents, my file contents, my file contents, my
 file contents, my file contents, my file contents, my file contents,
my
 file contents, my file contents, my file contents, my file contents, my
 file contents, my file contents, my file contents, my file contents
-----------------------e7b6ef072f
Content-Disposition: form-data; name="apsdb.ftsFields"
newNumericField4,field1,apsdb_attachments
 
 
-----------------------e7b6ef072f--

Creating A Scheduling Document

A scheduling document contains a defined set of reserved fields that control the execution of a script at a specific date and time.

Please refer to Scheduled Script for more details about scheduling scripts.

Updating a document

Documents submitted for updating must include the document key of the document apsdb.documentKey=[key]. The update parameter can take the following values: [true|false]. Any different value will not be allowed.

The update parameter apsdb.update and the document key parameter apsdb.documentKey are handled in the following way when sent:

When updating a field in a document, if the user tries to append to an existing value, the value type should match the existing field type or else the request will not be allowed. Note, however, that replacing the existing value with a new value of a different type is allowed. Replacing a value is done by sending a request with the document key and the same fieldName with a different value. Note, however, that updating a multivalue field to a single value will remove the multivalue fields.

If the user wishes to append to an existing field in an existing document, he can send the new values and set the apsdb.multivalueAppend to this fieldname. apsdb.multivalueAppend should contain a comma separated list of fieldNames the user wishes to append.

Appending will only add unique values to one field. If the user tries to create a duplicate field value, the action is ignored. Appending to a single value will make the field multivalued.

Users cannot append more than one file attachment per field, but can attach more than one file per document by creating multiple file attachment fields.

Deleting a field or a field value

Finally, to delete a field (single or multi-valued), the update request should send the field with an empty value. Note that deleting a field will delete all its values by sending fieldName with no value (e.g. apsdb.fieldName=)

Users can also delete fields by sending fieldName.apsdb.delete=valueToBeDeleted.

If the user sends fieldName.apsdb.delete with no value, the field with all its values will be deleted.

ACLs

When saving a document, field ACLs are verified

• Adding fields in the fts fields to be indexed cannot be done on fields the user doesn't have read access on
• Saving fields the user doesn't have write access on is not allowed
• Saving file fields the user doesn't have write access on is not allowed
• If a user has no write access to any field group including the dynamic fields, then he may not create/update a document.

Note: if you try to create/ or update a schema-less document but the configuration of your account does not allow for schema-less documents, you will get a "PERMISSION_DENIED" error  when calling "SaveDocument" even if your credentials are valid.

Overriding Schema and Default ACLs

In specific cases, the need to override ACLs set in the schema is required. One example of an application with such a use case is a wiki. First, let’s assume that all wiki pages are documents based on the same schema. Let us also assume that the schema allows only the creator to write to the wiki pages.

However, someone who created a page in a wiki may require adding contributors to help him update the page and write to it. This is the case where the user would need to override the ACLs set in the schema and give write ACLs to contributors. Please find the below example to better explain this concept.

<schema>
    <aclGroups>
     <aclGroup name="wikiPage">
         <read>all</read>
         <write>creator</write>
         <fields>
             <field>field1</field>
             <field>picture</field>
         </fields>
     </aclGroup>
     <defaultAcl>
         <read>all</read>
         <write>creator</write>
     </defaultAcl>
     <schemaAcl>
         <read>user1;user2;group:group1</read>
         <write>user1;user2;group:group1</write>
         <delete>user1;user2;group:group1</delete>
     </schemaAcl>
</aclGroups>
<fields>
     <field name="field1" type="string" />
     <field name="picture" type="file" />
</fields>
</schema>

The ACLs in the documents will take priority over the ones in the schema. So in order to override the ACLs in the “wikiPage” ACL group, the user can send wikiPage.writeACL parameter in the request. In order to override default ACLs, the user can send default.readACL or default.writeACL parameters in the request. To override the default delete ACL, the user must send document.deleteACL parameter in the request. Moreover, the document.readACL and document.writeACL parameters can be used to grant or deny read and write access to the document as a whole, and they override the field groups and dynamic fields (default) ACLs.

The following are the possible scenarios for overriding schema ACLs:

• A user who is in the "document writeACL" can modify who else is in the "document writeACL" and "document readACL"
• A user who is in the "document deleteACL" can modify who else is in the "document deleteACL"
• A user who is in the "default writeACL" can modify who else is in the "default writeACL" and "default readACL"
• A user who is in a "field group writeACL" can modify who else is in the "field group writeACL" and "field group readACL"

The following are the possible scenarios for overriding "schema-less" ACLs:

• A user who is in the "document writeACL" can modify who else is in the "document writeACL" and "document readACL"
• A user who is in the "document deleteACL" can modify who else is in the "document deleteACL"

Note that for "schema-less" documents, the "default writeACL" and the "default readACL" are meaningless. Instead, the "document writeACL" and the "document writeACL" should be used. In "schema-less" documents, all fields are supposed to be dynamic fields. However, and for technical reasons, the attached files fields cannot be dynamic, and hence needed to be defined in a field group in the default schema. This means that even if you try to override the "default readACL" and "default writeACL", this does not affect attached files fields. As a result, you are supposed to use the "document readACL" and "document writeCL" instead.

Also note that the "document writeACL" restricts EVERYTHING. That is, if a user is NOT in the "document writeACL", then he cannot do anything on the document even though he is a member of other ACLs. By default, the "document readACL" and "document writeACL" imply everyone in case they are not set.

Last but not least, the following rules apply for viewing the ACLs persisted with the document:

• A user who is in the "document readACL" can view the "document writeACL" and "document readACL" and "document deleteACL"
• A user who is in the "default readACL" can view the "default writeACL" and "default readACL"
• A user who is in a "field group readACL" can view the "field group writeACL" and "field group readACL"

Versioning

Versioning is an extra step that may occur when updating a document. It can be used to keep track of all changes to a document or to create new versions of a document at specific milestones.

A document is uniquely identified by its dockey and version number. Multiple versions of the same document have the same dockey, but different version numbers.

A document's schema may specify the type of versioning that the document supports. (Schemaless documents have disabled versioning). API calls to SaveDocument may use the following parameters to take advantage of this feature: apsdb.versioning and apsdb.latestVersion. Note that the first time a document is created, it is by default the first version. The versioning parameters should not be used when creating this first version --- versioning requires the apsdb.update parameter to also be true.

The apsdb.versioning parameter specifies whether this call of SaveDocument should create a new version of the document instead of updating the existing document.
The apsdb.latestVersion parameter specifies what is currently expected to be the latest version of the document. If it does not match what the actual latest version is, then the SaveDocument call will fail with a CANNOT_CREATE_VERSION ServiceException.

If you are not creating a new version of a document or if you are creating a new document, but you also specify the apsdb.latestVersion parameter, then an INVALID_REQUEST ServiceException will be thrown.

Anything that causes a contradiction to the above table will lead to an INVALID_PARAMETER_VALUE ServiceException being thrown. For instance, if versioning is disabled, but the apsdb.versioning parameter is sent as true, or if versioning is forced but apsdb.versioning is false, etc.

Note that the latest version of the document will inherit all ACLs from its previous version. If the previous version contains a document.writeACL that differs from the one specified in its schema, then the current values of its document.writeACL field will be saved under a new field called document.writeACL.previous, and its document.writeACL will be set to "nobody". This results in old versions  read-only, and a backup of the writeACL that was used. The following example illustrates this behavior:

Specific Request Parameters

(Refer to Common Request Parameters)

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element:

{
	"result":{
		"document":{
			"key":"the key of the document being created; this will be auto-generated if not provided by the user",            
       		"versionNumber":"the version number of the document being created"       
		}
	}
}

Specific Logical Errors

(Refer to Common Logical Error Codes)

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/SaveDocument?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsdb.store
apsdb.update=[true|false]
apsdb.documentKey
apsdb.globalDateFormat
[fieldName]=[fieldValue]
[fieldName].apsdb.fieldType=[fieldType]
[fieldName].apsdb.fieldDateFormat=[dateFormat]
apsdb.multivalueAppend=[fieldName1],[fieldName2],...[fieldNameN]

Sample XML Response

Success XML response:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
     <metadata>
         <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
         <status>success</status>       
     </metadata>
     <result>
        <document key="[document_key]" versionNumber="[document_versionNumber]"/>
     </result>
</response>

Failure XML response:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
     <metadata>
         <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
         <status>failure</status>
         <errorCode>[errorCode]</errorCode>
         <errorDetail>[failMsg]</errorDetail>
     </metadata>
</response>

Sample JSON Response

{"response": {
  "metadata": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "success"
  },
  "result": {
    "document": {
      "key": "00A84E82A116C2BE1FD57E5399E8F8D4",
      "versionNumber": "1.0"
    }
  }
}}