|
POST |
What does it do?
Upload and create an asset.
This call will create a new asset in Assets Server. It can be used to upload files into Assets Server. It can also be used to create 'virtual' assets such as Collections. In that case no file has to be uploaded.
When you want to create a new asset, certain metadata is required. The metadata is needed to determine where the file will be stored in Assets Server.
Tip: The create service behaves almost identical to the update service. The update service has an additional 'id' parameter to specify the asset that should be updated.
|
Note: The Create call automatically renames a file when not explicitly passing a name as metadata. Background info: While the Create service does not support the FileReplacePolicy, it does allow the autoRename argument (with True as the default). When passing 'name' or 'filename' as metadata to give the new file a custom name, and this name conflicts with an existing file, the PathAlreadyExistsException is still in effect. As a work-around, a custom 'name' can be passed within the file object in the Post fields. When this name conflicts, the autoRename is activated (but not if explicitly passing name as part of the metadata). |
Log in requirement
Before being able to request information from Assets Server by using a GET request or make changes to the system through a POST request, a log in to Assets Server is required. For information about the available APIs for logging in, see Assets Server REST API - introduction.
POST requests only
This REST API only accepts POST requests, not GET requests. Also, the POST request needs to include a cross-site request forgery (csrf) token.
The csrf token is a unique code which, by including it in the request, also makes the POST request unique and therefore much more secure.
The csrf token is obtained by first logging in to Assets Server through a POST request. The response that is received will include the csrf token which can then be used in subsequent POST requests as a http header:
"X-CSRF-TOKEN: <some_csrf_token>"For more information including examples, see Assets Server REST API - Performing a POST request with a csrf token.
Parameters
| Filedata |
The file to be created in Assets Server. If you do not specify a filename explicitly through the metadata, the filename of the uploaded file will be used. The parameter is named "Filedata" because that is the standard name used by flash uploads. This makes it easy to use flash uploaders to upload batches of files to Assets Server. Optional. If omitted, a 0kb placeholder file will be created. |
| metadata |
A JSON encoded object with properties that match Assets Server metadata field names. This metadata will be set on the asset in Assets Server. Optional. You can also use parameters matching Assets Server field names. |
|
metadataToReturn |
Comma-delimited list of metadata fields to return in hits. It is good practice to always specify just the metadata fields that you need. metadataToReturn=name,rating,assetCreated Specify "all", or omit to return all available metadata. metadataToReturn=all Leave 'empty' to return only minimal fields metadataToReturn= Optional. Default returns all fields. |
| * |
Any parameter matching an Assets Server metadata field name will be used as metadata. This metadata will be set on the asset in Assets Server. Optional. You also use the 'metadata' parameter. |
| nextUrl |
When specified, the service will send a 301 redirect to this URL when it is completed successfully. If you place '${id}' in the URL, it will be replaced with the Assets Server asset id of the created asset. Optional. If omitted, a simple 200 OK status code will be returned. Note: This must be a relative URL on the same domain as the Assets Server. If you do specify an absolute URL with a domain, only the part of the URL after the domain will be used to redirect to. |
| autoRename |
When a file with the same file name already exists in the system, it will fail with an PathAlreadyExistsException. By adding the autoRename=true parameter, the file is upload with an incremental number added to the end of the file name, for example: image-1.jpg Optional. Default is false, auto-renaming files is off. |
Return value
Depending if a nextUrl is specified, this service will either send a 301 redirect, or return a JSON response with a hit containing all info and metadata about the created asset.
If the operation fails, an error page with a 500 error status will be returned.
Examples
Upload form
This simple HTML form uploads a file into Assets Server, into the folder /Upload Zone:
<form action="http://demo.assets-server.com/services/create"
method="post" enctype="multipart/form-data">
<input type="hidden" name="nextUrl" value="...mypage.html#${id}">
<input type="hidden" name="folderPath" value="/Upload Zone">
<label for="file">File </label>
<input type="file" name="Filedata" id="file">
<br><br>
<input type="submit" value="Create">
</form>Tip: The auto-organize mechanism will put the file into /Upload Zone/Auto organized/(year)/(date) to keep the top-level folder organized.
Creating collections
The following call creates a new empty collection in /Demo Zone/Collections:
|
create http://demo.assets-server.com/services/create
?folderPath=/Demo Zone/Collections
&assetType=collection
&name=My Collection
|
As you can see, the location of the asset is specified using several metadata fields. If you want to specify this with one field, use the assetPath field, which contains the complete path including the filename:
|
create http://demo.assets-server.com/services/create
?assetPath=/Demo Zone/Collections/My Collection.collection
|
The JSON result returned by the service has the following format and information. If you upload a real file, like an image instead of creating a virtual asset like the collection above, the result will also have thumbnail and preview URLs:
{
"permissions" : "VPUMECD",
"id" : "0pBENZZH4ro9pRuHSAAlYr",
"metadata" : {
"assetPath" : "/Demo Zone/Collections/My Collection.collection",
"assetCreator" : "admin",
"folderPath" : "/Demo Zone/Collections",
"assetModified" : {
"value" : 1297422957338,
"formatted" : "2011-02-11 12:15:57 +0100"
},
"metadataComplete" : "true",
"assetCreated" : {
"value" : 1297422957338,
"formatted" : "2011-02-11 12:15:57 +0100"
},
"extension" : "collection",
"assetModifier" : "admin",
"assetType" : "collection",
"name" : "My Collection",
"assetRevision" : 1,
"filename" : "My Collection.collection",
"assetDomain" : "container"
},
"thumbnailHits" : [ ],
"originalUrl" : "http://localhost:8080/controller/file/Demo%20Zone/Collections/My%20Collection.collection"
}
Comments
3 comments
Would you mind adding documentation for nesting collections with “/services/collection/add?collectionId=$A_ID&childIds=$B_ID"
Thanks
Hi Andres,
I have forwarded your request to our Development team. I will let you know the outcome when I get their response.
Best regards,
Maarten van Kleinwee
Senior Technical Writer, WoodWing Software
Hi Andres,
The reply I got from the developers is that this this is a private API and that as such it is a deliberate choice not to include it in the documentation.
Best regards,
Maarten van Kleinwee
Senior Technical Writer, WoodWing Software
Please sign in to leave a comment.