POST source api

POST to a Source

The record describing a typical Source (or Attachment area) looks similar to this (Check the GET-api for complete documentation on the values returned):

{
    "is-breakable": false, 
    "name": "Attachments",
    "files": [
        {
            "content-type": "application/excel", 
            "name": "4-sale-web.xls", 
            "number-of-pages": 1, 
            "props": {
                "DisplayName": "4-sale-web.xls", 
                "isDownload": "true", 
                "isVisible": "true", 
                "rel": ""
            }, 
            "size": 93696, 
            "url": "/amazonec2/~~Attachments/4-sale-web.xls"
        }, 
        {
            "content-type": "application/msword", 
            "date-uploaded": "2013-05-08 12:52:03.077", 
            "name": "GettingStartedTips.doc", 
            "number-of-pages": 1, 
            "props": {
                "DisplayName": "getting started tips", 
                "isDownload": "true", 
                "isVisible": "true", 
                "rel": ""
            }, 
            "size": 105472, 
            "url": "/amazonec2/~~Attachments/GettingStartedTips.doc"
        }, 
        {
            "content-type": "application/url", 
            "date-uploaded": "2014-03-27 17:25:27.528", 
            "name": "/url-value/remote.htm", 
            "number-of-pages": 1, 
            "props": {
                "DisplayName": "This is a URL", 
                "isDownload": "false", 
                "isUrlName": "true", 
                "isVisible": "true", 
                "rel": "lightbox"
            }, 
            "size": 0, 
            "url": "/amazonec2/~~Attachments//url-value/remote.htm"
        }
    ]
}

A POST to a source's management URL will update that source in accordance with the operation field specified in the request. Like other update operations, the record is based to the record returned from GET, but will generally have fields only for updatable properties of the object.

The is-breakable and name fields of a Source cannot be changed. These aspects of a Source are defined in the document's MetaType. As they are not updateable, they are not required.

The files field contains an array of records containing metadata for each individual file in the source which should be updated. Each record is interpreted as it would normally be interpreted in an individual POST update of the metadata for the file directly, as described in POST-source-file-api. A Source update operation selects the files to be updated by their name, meaning that name is a read-only property when updating multiple files in one operation. This means that renaming of files is only possible by means of a direct update using the management URL for a file.

The operation field selects files to be updated in the following ways, based on the value of the operation field:

• add-update This operation will go through each element of the files array and update or replace the earlier information for that file with the new information provided. Files are always identified by their name, which holds the URL of an externally stored resource, so updating a URL essentially always amounts to deleting the old URL, and creating a new one. It is not possible to delete a file by means of this operation.
• replace This operation will update the files of a source to match the given list, deleting any other files that may be in the source.

Using replace to update file metadata only: you can use the replace operation to replace the metadata for a number of existing files, and to delete files not on the list, without incurring the obligation to re-upload the content of previously created files. The criterion for identity is the name of a file, which is its primary key within a source. This means that replace is safe to use to update a file list without requiring the retransmission of all content.

Note: neither add-update, nor replace, will delete the file content of a file that has content, unless the file itself is deleted from the source. The only exception is that if a file is changed to a URL reference by altering the "isUrlName" property of the file, the system's behavior with respect to retention of that content is currently undefined. Contact Tizra, if you have an application for a specific behavior in this area.

Note: You can create a new file with add-update, but just as with POSTing metadata to a source-file URL to create a new file, the content of the file will have to be separately uploaded by a PUT operation.