Assets Server REST API - update / check-in

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

What does it do?

This call updates an existing asset in Assets Server with a new file. It can also be used to update metadata.

Tip: The update service behaves almost identical to the create service. The update service has an additional 'id' parameter to specify the asset that should be updated.

Update equals check-in

When an asset is checked-out and FileData is added through the Update API, the asset is checked-in, meaning that all checkedOut fields are reset. In this context, the update action is considered to be the same as a 'check-in' action. This default behavior can be turned off by adding the clearCheckoutState parameter to the update call. For more information, see the Parameters table below.

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 an empty 200 OK status.

If the operation fails, an error page with a 500 error status will be returned.

Examples

Upload and replace file

This simple HTML form updates an existing asset:

<form action="http://demo.assets-server.com/services/update"
   method="post" enctype="multipart/form-data">
  <input type="hidden" name="nextUrl" value="...mypage.html#${id}">
  <input type="hidden" name="id" value="5LMAQTW9qfhANn7f6JJVpl">
  <label for="file">File </label>
  <input type="file" name="Filedata" id="file">
  <br><br>
  <input type="submit" value="Update">
</form>

Update metadata with form

The following updates the rating of the asset:

<form action="http://demo.assets-server.com/services/update"
   method="post">
  <input type="hidden" name="nextUrl" value="...mypage.html#${id}">
  <input type="hidden" name="id" value="5LMAQTW9qfhANn7f6JJVpl">
  <label for="rating">Rating </label>
  <input type="text" name="rating" id="rating" value="4">
  <label for="status">Status </label>
  <select name="status" id="status">
    <option>New</option>
    <option>Draft</option>
    <option>Production</option>
    <option>Review</option>
    <option>Correction</option>
    <option>Final</option>
  </select>
  <br><br>
  <input type="submit" value="Update">
</form>

Update metadata with AJAX and field parameters

Submitting the form has the same effect as the following AJAX call.

http://demo.assets-server.com/services/update
    ?id=5LMAQTW9qfhANn7f6JJVpl
    &rating=4
    &status=New

Update metadata using JSON

Passing metadata as separate parameters is very useful when working with HTML forms. For AJAX calls it can be easier to pass metadata as a JSON encoded string. The following will set the rating to "Rejected" (-1) and will change the status to "Correction".

http://demo.assets-server.com/services/update
    ?id=5LMAQTW9qfhANn7f6JJVpl
    &metadata={rating: -1, status: "Correction"}

Clear metadata

To clear the value for a metadata field, pass an empty string for that field.

http://demo.assets-server.com/services/update
    ?id=5LMAQTW9qfhANn7f6JJVpl
    &rating=
    &status=

Add values to existing metadata

Using an update, you can append or remove existing metadata on an asset. For example, you could add a tag to the asset while leaving the current tags intact.

Tip: You need to escape the '+' character with %2B if you use it in URLs. A plain '+' would be interpreted as a space character (as defined in the specification on URL encoding).

The following call will remove the "house" tag from the asset, while at the same time adding the tags "beach", "villa", "sunny". If the asset has the tags "sea", "bay", those would not be removed. If the assets has the tag "villa", it will not get "villa" twice, assets can only have a specific tag once.

http://demo.assets-server.com/services/update
    ?id=5LMAQTW9qfhANn7f6JJVpl
    &tags=%2Bbeach, -house, %2Bvilla, %2Bsunny

It is also possible to append text to a single value field using the '+' character or add text around the existing value using {CURRENT}.

http://demo.assets-server.com/services/update
    ?id=5LMAQTW9qfhANn7f6JJVpl
    &description=%2Bhouse
    &subject=before{CURRENT}after

Update metadata and File upload using curl

Update asset with filedata only. For authcred see: Assets Server API - authcred.

curl -F "id= 5LMAQTW9qfhANn7f6JJVpl" -F "Filedata=@/Path/To/File.jpg" http://demo.assets-server.com/services/update?authcred=YWRtaW46Y2hhbmdlbWVub3c=

Update asset with filedata and update metadata

curl -F "id= 5LMAQTW9qfhANn7f6JJVpl" -F "Filedata=@/Path/To/File.jpg" - F "metadata={rating:-1,status:\"Correction\"}" http://demo.assets-server.com/services/update?authcred=YWRtaW46Y2hhbmdlbWVub3c=

Note: If the file name or metadata is quoted by using double-quotes, any double-quote or backslash within the file name or value must be escaped by a backslash.