Assets Server REST API - create

http://yourserver.com/services/create
    ?Filedata=<multipart/form-data encoded file>
    &metadata=<JSON encoded metadata>
    &<Elvis metadata field name>=<value>
    &metadataToReturn=<comma-delimited fields>						
    &nextUrl=<next URL>
    &autoRename=<true>

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 and Assets Server will create a 0 kb placeholder for the virtual asset.

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.

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

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:

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:

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"
}