module WoodWing::Elvis::Rest
Public Instance Methods
elvis.tenderapp.com/kb/api/rest-browse
browse folders and show their subfolders and collections, similar to how folder browsing works in the Elvis
desktop client.
Note: Even though it is possible to return the assets in folders,
doing so is not advised. The browse call does not limit the number of results, so if there are 10000 assets in a folder it will return all of them. It is better to use a search to find the assets in a folder and fetch them in pages.
yourserver.com/services/browse
?path=<assetPath> &fromRoot=<folderPath> &includeFolders=<true|false> &includeAssets=<true|false> &includeExtensions=<comma-delimited extensions>
Options
path (Required) The path to the folder in Elvis you want to list. Make sure the URL is properly URL-encoded, for example: spaces should often be represented as %20. fromRoot Allows returning multiple levels of folders with their children. When specified, this path is listed, and all folders below it up to the 'path' will have their children returned as well. This ability can be used to initialize an initial path in a column tree folder browser with one server call. Optional. When not specified, only the children of the specified 'path' will be returned. Available since Elvis 2.6 includeFolders Indicates if folders should be returned. Optional. Default is true. includeAsset Indicates if files should be returned. Optional. Default is true, but filtered to only include 'container' assets. includeExtensions A comma separated list of file extensions to be returned. Specify 'all' to return all file types. Optional. Default includes all 'container' assets: .collection, .dossier, .task
# File lib/woodwing/elvis/rest/browse.rb, line 53 def browse(options={}) Utilities.demand_required_options!( :browse, options ) url = base_url + "browse" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-checkout
# File lib/woodwing/elvis/rest/checkout.rb, line 7 def checkout(options={}) url = base_url + "checkout" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-create Upload and create an asset.
This call will create a new asset in Elvis
. It can be used to upload files into Elvis
. It can also be used to create 'virtual' assets like collections. In that case no file has to be uploaded and Elvis
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 Elvis
.
yourserver.com/services/create
?Filedata=<multipart/form-data encoded file> &metadata=<JSON encoded metadata> &<Elvis metadata field name>=<value> &nextUrl=<next URL>
Options
Filedata The file to be created in Elvis. If you do not specify a filename explicitly through the metadata, the filename of the uploaded file will be used. NOTE: 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, a 0kb placeholder file will be created. See the method create_collection() 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. 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 Elvis asset id of the created asset. Optional. If omitted, a simple 200 OK status code will be returned
# File lib/woodwing/elvis/rest/create.rb, line 48 def create(options={}) Utilities.demand_required_options!( :create, options ) # SMELL: Don't think this is required since last change to # get_response_with_post options.merge!( { multipart: true } ) url = base_url + "create" response = get_response_using_post(url, options) end
elvis.tenderapp.com/kb/api/rest-createauthkey
# File lib/woodwing/elvis/rest/authorization_keys.rb, line 7 def create_auth_key(options={}) url = base_url + "create_auth_key" response = get_response(url, options) end
Create an '.elvislink' file
/yourfilename.elvislink ?action=openAuthkey | openAssets | openContainers | activateContainers | openSearch | openBrowse &key=<authkey to open and link to the user> &containerIds=<collection id's to open or activate> &assetIds=<assets to open> &q=<query for search> &sort=<sort for search> &folderPath=<folderPath to open> &includeSubFolders=true|false
What does it do?
Produce an '*.elvislink' file that will open the desktop client and perform an action. Some actions that can be performed:
Show results sent by an email link (authkey). Open a search. Show a specific asset.
Available since Elvis
2.6
Parameters
action The action that should be performed when the link file is opened in
the desktop client. See the elvisContext functions for the possible actions. Optional. Not needed when you specify the 'key' parameter. In that case the openAuthkey action is automatically used.
key An authkey to be opened and displayed in the desktop client. The
permissions granted by the authkey will be linked to the user when opened. Optional. Only needed if you want to open an authkey.
other parameters For detailed descriptions of the other parameters, see the elvisContext functions.
Return value
The service produces an XML file with the extension '.elvislink'. The file also includes the server URL so the desktop client can connect to the correct server.
Examples
openAuthkey elvislink
http://demo.elvisdam.com/elvislink ?key=9T_WLil348lBtFk8FDTwPN This URL generates: openAuthkey-2011_11_328-144355.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <openAuthkey authkey="9T_WLil348lBtFk8FDTwPN"/> </elvisLink>
openSearch elvislink
http://demo.elvisdam.com/elvislink/openBeaches.elvislink ?action=openSearch&q=beach&sort=name This URL generates: openBeaches.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <openSearch q="beach" sort="name"/> </elvisLink>
openBrowse elvislink
http://demo.elvisdam.com/elvislink/openTrailers.elvislink ?action=openBrowse &folderPath=/Demo Zone/Videos/Movie Trailers &includeSubFolders=true &sort=assetCreated This URL generates: openTrailers.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <openBrowse folderPath="/Demo Zone/Videos/Movie Trailers" includeSubFolders="true" sort="assetCreated"/> </elvisLink>
openAssets elvislink
http://demo.elvisdam.com/elvislink ?action=openAssets &assetIds=Bg7fObz1aVr96wy97riUad,0l2ZhcAfK779hCXqTf2E7s This URL generates: openAssets-2011_11_328-140254.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <openAssets assetIds="Bg7fObz1aVr96wy97riUad,0l2ZhcAfK779hCXqTf2E7s"/> </elvisLink>
openContainers elvislink
http://demo.elvisdam.com/elvislink/openCollections.elvislink ?action=openContainers &containerIds=0JkPrbQc40g8RQIC1NI6uo,6BN2FRaCqyLA5DjJJdB9h4 &sort=name This URL generates: openCollections.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <openContainers containerIds="0JkPrbQc40g8RQIC1NI6uo,6BN2FRaCqyLA5DjJJdB9h4" sort="name"/> </elvisLink>
activateContainers elvislink
http://demo.elvisdam.com/elvislink ?action=activateContainers &containerIds=0JkPrbQc40g8RQIC1NI6uo,6BN2FRaCqyLA5DjJJdB9h4 This URL generates: activateContainers-2011_11_328-142851.elvislink <?xml version="1.0" encoding="UTF-8"?> <elvisLink serverUrl="http://demo.elvisdam.com"> <activateContainers containerIds="0JkPrbQc40g8RQIC1NI6uo,6BN2FRaCqyLA5DjJJdB9h4"/> </elvisLink>
# File lib/woodwing/elvis/rest/create_elvislink.rb, line 137 def create_elvislink(options) Utilities.demand_required_options!( :elvislink, options ) url = base_url + "elvislink" response = get_response_using_get(url, options) end
elvis.tenderapp.com/kb/api/rest-create_folder
# File lib/woodwing/elvis/rest/folders.rb, line 7 def create_folder(options={}) Utilities.demand_required_options!( :create_folder, options ) url = base_url + "createFolder" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-create_relation
# File lib/woodwing/elvis/rest/relations.rb, line 7 def create_relation(options={}) url = base_url + "create_relation" response = get_response(url, options) end
A successful log in will result in a cookie
# File lib/woodwing/elvis/rest/login_logout.rb, line 11 def logged_in? not @cookies.empty? end
FIXME: Need to change Elvis
to https otherwise anyone who snoops
the wire will find cred and be able to have complete access once the white listed IP scheme has been dropped.
# File lib/woodwing/elvis/rest/login_logout.rb, line 158 def login(options={}) raise AlreadyLoggedIn unless @cookies.empty? unless options.include?(:cred) options = { username: ENV['ELVIS_USER'], password: ENV['ELVIS_PASS'] }.merge(options) options[:cred] = UrlSafeBase64.encode64("#{options[:username]}:#{options[:password]}") end options.delete(:username) options.delete(:password) options[:clientType] = 'api_Ruby' options[:returnProfile] = 'true' url = base_url + "login" response = get_response(url, options) return response end
# https://elvis.tenderapp.com/kb/api/rest-logout
yourserver.com/services/logout
Terminates your browser session. Use this to end a session using an AJAX call.
Available since Elvis
2.6.
Parameters
This service has no parameters
Return value
# File lib/woodwing/elvis/rest/login_logout.rb, line 239 def logout(options={}) url = base_url + "logout" response = get_response(url, options) @cookies = {} if response[:logoutSuccess] return response end
elvis.tenderapp.com/kb/api/rest-remove
# File lib/woodwing/elvis/rest/folders.rb, line 15 def remove_folder(options={}) Utilities.demand_required_options!( :remove_folder, options ) url = base_url + "remove" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-remove_relation
# File lib/woodwing/elvis/rest/relations.rb, line 14 def remove_relation(options={}) url = base_url + "remove_relation" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-revokeauthkeys
# File lib/woodwing/elvis/rest/authorization_keys.rb, line 23 def revoke_auth_keys(options={}) url = base_url + "revoke_auth_keys" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-search Search assets in Elvis
using all of the powerful search functions provided by the Elvis
search engine. You can execute all possible queries and even use faceted search.
Returned information can be formatted as JSON, XML or HTML to support any kind of environment for clients.
Apart from all sorts of metadata about the assets, the results returned by a search call also contain ready-to-use URLs to the thumbnail, preview and original file. This makes it extremely easy to display rich visual results.
yourserver.com/services/search
?q=<query> &start=<first result> &num=<max result hits to return> &sort=<comma-delimited sort fields> &metadataToReturn=<comma-delimited fields> &facets=<comma-delimited fields> &facet.<field>.selection=<comma-delimited values> &format=<json|xml|html> &appendRequestSecret=<true|false>
Options
q (Required) The query to search for, see the query syntax guide for details. https://elvis.tenderapp.com/kb/technical/query-syntax Recap: supports wildcards: *? logical: AND && OR || prefix terms with + to require - to remove suffix terms with ~ to include similar (eg. spelling errors) terms seperated by spaces default to an AND condition use "double quotes" to search for phrases. All searches are case insensitive. start First hit to be returned. Starting at 0 for the first hit. Used to skip hits to return 'paged' results. Optional. Default is 0. num Number of hits to return. Specify 0 to return no hits, this can be useful if you only want to fetch facets data. Optional. Default is 50. sort The sort order of returned hits. Comma-delimited list of fields to sort on. By default, date/time fields and number fields are sorted descending. All other fields are sorted ascending. To explicitly specify sort order, append "-desc" or "-asc" to the field. Some examples: sort=name sort=rating sort=fileSize-asc sort=status,assetModified-asc A special sort case is "relevance". This lets the search engine determine sorting based on the relevance of the asset against the search query. Relevance results are always returned descending. Optional. Default is assetCreated-desc.
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. This will make the searches faster because less data needs to be transferred over the network. Example: metadataToReturn=name,rating,assetCreated Specify "all", or omit to return all available metadata. Example: metadataToReturn=all metadataToReturn= Optional. Default returns all fields.
facets Comma-delimited list fields to return facet for.
Example: facets=tags,assetDomain Selected values for a facet must be specified with a "facet.<field>.selection" parameter. Do not add selected items to the query since that will cause incorrect facet filtering. Note: Only fields that are un_tokenized or tokenized with pureLowerCase analyzer can be used for faceted search Optional. Default returns no facets.
facet.<field>.selection Comma-delimited list of values that should
be 'selected' for a given facet. Example: facet.tags.selection=beach facet.assetDomain.selection=image,video Optional.
format Response format to return, either json, xml or html.
json format is lightweight and very suitable for consumption using AJAX and JavaScript. html format is the easiest way to embed results in HTML pages, but is heavier and less flexible than using a HitRenderer from our open-source JavaScript library. xml format is the same as returned by the Elvis SOAP webservice search operation. This format is suitable for environments that do not support JSON parsing and work better with XML. When you use format=xml, error responses will also be returned in xml format. Optional. Default is json. appendRequestSecret When set to true will append an encrypted code to the thumbnail, preview and original URLs. This is useful when the search is transformed to HTML by an intermediary (like a PHP or XSLT) and is then served to a web browser that is not authenticated against the server. Optional. Default is false.
RETURNED VALUE
¶ ↑
An array of hits in JSON, XML or HTML format. Each item in the array has the following properties.
firstResult Index of the first result that is returned. maxResultHits Maximum number of hits that are returned. totalHits Total hits found by the search.
hits
id Unique ID of the asset in Elvis. permissions String that indicates the permissions the current user has for the asset. thumbnailUrl A ready to use URL to display the thumbnail of an asset. Only available for assets that have a thumbnail. previewUrl A ready to use URL to display the default preview of an asset. The type of preview depends on the asset type. Only available for assets that have a preview. originalUrl A ready to use URL to download the original asset. This URL will only work if the user has the 'use original' permission for this asset. This can be checked with the 'permissions' property. metadata An object with metadata that was requested to be returned. Some metadata will always be returned.
Fields that have date or datetime values and the field fileSize contain both the actual numerical value and a formatted value.
# File lib/woodwing/elvis/rest/search.rb, line 135 def search(options={}) Utilities.demand_required_options!( :search, options ) url = base_url + "search" # NOTE: One element of metadata is 'textContent' for books and # large articles that is a LOT of text. The following # line changes the default from 'all' to 'status,name'. # If you want all metadata then you have to request # 'all' in your options. options = { metadataToReturn: 'status,name' }.merge(options) response = get_response(url, options) end
# File lib/woodwing/elvis/rest/stub.rb, line 6 def stub(); end
elvis.tenderapp.com/kb/api/rest-undo_checkout
# File lib/woodwing/elvis/rest/checkout.rb, line 14 def undo_checkout(options={}) url = base_url + "undo_checkout" response = get_response(url, options) end
elvis.tenderapp.com/kb/api/rest-update_auth_key
# File lib/woodwing/elvis/rest/authorization_keys.rb, line 14 def update_auth_key(options={}) url = base_url + "update_auth_key" response = get_response(url, options) end