Logo Help Center

Elvis 5 REST API - update

Elvis 5 REST API - update

GET/POST

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>

What does it do?

This call updates an existing asset in Elvis 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.

Parameters

id

The Elvis id of the asset to be updated.

Required.

Filedata

The file to be updated in Elvis.

If you do not specify a file name explicitly using the metadata above, the file name 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 Elvis.

Optional. If omitted, only metadata will be updated.

metadata

A JSON encoded object with properties that match Elvis metadata field names. This metadata will be set on the asset in Elvis.

Optional. You can also use parameters matching Elvis field names.

*

Any parameter matching an Elvis metadata field name will be used as metadata. This metadata will be set on the asset in Elvis.

Optional. You also use the 'metadata' parameter.

metadataToReturn

Info: Requires Elvis 5.5.3 or higher.

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.

nextUrl

When specified, the service will send a 301 redirect to this URL when it completes successfully. If you place '${id}' in the URL, it will be replaced with the Elvis asset id of the updated 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 Elvis 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.

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.elvisdam.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.elvisdam.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.

update

http://demo.elvisdam.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".

update
http://demo.elvisdam.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.

update
http://demo.elvisdam.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.

update
http://demo.elvisdam.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}.

update
http://demo.elvisdam.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: Elvis 5 API - authcred.

curl -F "id= 5LMAQTW9qfhANn7f6JJVpl" -F "Filedata=@/Path/To/File.jpg" http://demo.elvisdam.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.elvisdam.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.

Document history

  • 20 February 2017: Updated code for example 'Update metadata and File upload using curl'.
  • 20 February 2017: Updated code for example 'Update asset with filedata and update metadata'.
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

2 Comments

  • 0
    Avatar
    Hans Bolten

    Additional information:
    A version is created if the `createVersion=true` request parameter is passed or when the field `keepVersion` in the asset metadata is set to `true`

     

  • 0
    Avatar
    Samuli Jokipaltio

    @Hans, a version is created by default, at least with v5.20.

    Instead, if "createVersion=false" is passed, it *seems* like no version is created (in version history). 
    But every update creates a new file in assetFilestore. 

    Edited by Samuli Jokipaltio
Please sign in to leave a comment.