Using the Asset REST API
Intro:
This document will explain what you can do with the page REST API to help edit content within CM1. It will cover how to retrieve, create, and edit Assets. Assets can be located in the finder.
NOTE: When sending requests to the server they should all be of type application/json.
Get an Asset (Metadata)
What you must know:
The full path including filename
Use Case:
You need the information about the asset object.
How to execute:
Execute a GET request against the CM1 instance (http://myCM1:9992) with the folder path /Assets/uploads and filename test.jpg
Example #1:
GET http://myCM1:9992/Rhythmyx/rest/assets/by-path/Assets/uploads/test.jpg
Response:
{
"fields": {
"displaytitle": "My Image",
"resource_link_title": null,
"filename": "test.jpg",
"alttext": null
},
"id": "16777215-101-852",
"name": "test.jpg",
"type": "percImageAsset",
"folderPath": "Assets/uploads",
"workflow": {
"name": "Default Workflow",
"state": "Draft",
"checkedOut": true,
"checkedOutUser": ""
},
"lastModifiedDate": "2014-11-07T19:53:48.000+0000",
"createdDate": "2014-11-04T22:26:07.000+0000",
"image": {
"filename": null,
"extension": "jpg",
"size": 171954,
"type": "image/jpeg",
"width": 1024,
"height": 768
},
"thumbnail": {
"filename": "thumb_test.jpg",
"extension": "jpg",
"size": 1310,
"type": "image/jpeg",
"width": 50,
"height": 38
}
}
Get an Asset (Binary)
A separate request is made to extract the binary file for an asset. The “Content-Type” header is set to the type of the file e.g. “image/jpg” and the Content-Disposition header contains the filename. "Content-Disposition": "attachment; filename=uploads/test.jpg"
What you must know:
The full path including filename
Use Case:
You need the binary for a file, image or flash asset
How to execute:
Execute a GET request against the CM1 instance (http://myCM1:9992) with the folder path /Assets/uploads and filename test.jpg
Example #1:
GET http://myCM1:9992/Rhythmyx/rest/assets/binary/Assets/uploads/test.jpg
Response:
The Binary file is returned, including content type header and filename in content-disposition, will download the file in a browser.
Create a Binary Asset
What you must know:
The filename you want to upload the binary as.
Use Case:
You need the binary for a file, image or flash asset
How to execute:
Execute a muiltipart/form-data post with the file sent as a “file” field, with a path field as the full asset path including filename e.g. Assets/uploads/test.jpg and optionally an assetType
Note: For Binary assets e.g. file, image and flash, you must first upload the binary file and then optionally modify the metadata in a separate request if required. Currently the binary contained in an asset cannot be modified. The old asset can be deleted and then the new file can be uploaded to the same path.
File upload is done as a multipart form. The binary is uploaded using a multipart form post and not json. The filename of the uploaded file is ignored, the filename will be created based upon the filename specified in the post url. The assetType field is optional it will override the asset type used instead of working out based upon the file mimetype. e.g. to upload an image into a file type. Options are file, flash, or image .
The following is an example form showing the format of the fields. Different client apis handle form posts in their own way, check out instructions for multipart/form-data for your api. The field name for the file itself must be “file”
The api will return the status of the asset metadata after creating the asset.
Response:
The asset metadata is returned
{
"fields": {
"displaytitle": "test2.jpg",
"resource_link_title": null,
"filename": "test2.jpg",
"alttext": null
},
"id": "16777215-101-858",
"name": "test2.jpg",
"type": "percImageAsset",
"folderPath": "Assets/uploads",
"workflow": {
"name": "Default Workflow",
"state": "Draft",
"checkedOut": true,
"checkedOutUser": ""
},
"lastModifiedDate": "2014-11-17T21:59:38.000+0000",
"createdDate": "2014-11-17T21:59:38.000+0000",
"image": {
"filename": "test2.jpg",
"extension": ".jpg",
"size": 173871,
"type": "image/jpeg",
"width": 1024,
"height": 768
},
"thumbnail": {
"filename": "thumb_test2.jpg",
"extension": "jpg",
"size": 1305,
"type": "image/jpeg",
"width": 50,
"height": 38
}
}
Update Binary Asset Metadata
For Binary assets e.g. file, image and flash, you must first upload the binary file as in the last step and then optionally modify the metadata in a separate request if required. Currently the binary itself contained in an asset cannot be modified. The old asset can be deleted and then the new file can be uploaded to the same path.
Example #1:
This example shows updating just the display title and alt text for a binary. You only need to specify the fields you want to modify. You cannot currently change the values in image, file or thumbnail sections. These values are read only.
http://myCM1:9992/Rhythmyx/rest/assets/by-path/Assets/uploads/test.jpg
Payload:
NOTE: If you include the id when you execute a PUT it must match the id of the object at the specified PUT URL. If you are creating a new object you should not include the id. Only the values in fields
{
"fields": {
"displaytitle": "New Display Title",
"alttext": “alt text”
}
}
Example #2:
This example shows setting the workflow state of a binary asset. See Page API for more information on workflow changes. The asset api works the same way for workflow.
PUT http://myCM1:9992/Rhythmyx/rest/assets/by-path/Assets/uploads/test.jpg
Payload:
{
"fields": {
"displaytitle": "New Display Title",
},
"workflow": {
"state": "Public",
}
}
Create or Update non binary shared Asset
Unlike binary assets, other assets can be created with the same request to update as long as all fields required by the UI have been specified. Each asset type has its own unique set of fields and type name. If in doubt doing a get request on an asset with the same fields as you would like is a good way to find the required format and name of these fields. Outlined below are all the current non binary assets. For updates any field not specified will not be modified. Some asset types have special internal formats like Comments form and care should be taken if trying to create or update these through the api.
http://myCM1:9992/Rhythmyx/rest/assets/by-path/Assets/uploads/assetName
Payload:
All the asset types can have workflow specified as in the binary assets above. The minimum for an asset is to specify the required fields and the type
Simple Text
{
"fields": {
"text": "<div class=\"rxbodyfield\"><p>Text <strong>bold</strong></p></div>"
},
"type": "percSimpleTextAsset"
}
Archive
{
"fields": {
"query_site_path": "//Sites",
"displaytitle": "Archive Title",
"archive_page_result": null,
"query_published_after": "12/17/2014",
"query_template_list": null,
"query_published_before": "12/31/2014",
"query_string": "select rx:sys_contentid, rx:sys_folderid from rx:percPage where jcr:path like '//Sites/%' and rx:page_title like '%Title contains%' and rx:sys_contentpostdate >='2014/12/17' and rx:sys_contentpostdate <='2014/12/31'",
"query_title_contains": "Title contains"
},
"type": "percArchiveList",
}
Auto List
{
"fields": {
"displaytitle": "Auto List Title",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:PSWidget_SimpleText where jcr:path like '//Folders%'",
"max_results": "10"
},
"type": "percSimpleAutoList",
}
Blog Post
{
"fields": {
"displaytitle": "BlogPostTitle",
"postbody": "<div class=\"rxbodyfield\"><p>Blog bost body</p></div>",
"authorname": null
},
"type": "percBlogPostAsset"
}
Calendar asset
{
"fields": {
"calendar_unique_name": "calendar-title",
"calendar_title": "Calendar Title",
"full_calendar_page": "/index",
"calendar_start_date": "2014-12-17 00:00:00.0"
},
"type": "percCalendarAsset",
}
Category
{
"fields": {
"displaytitle": "category title",
"end_date": "12/31/2014",
"title_contains": "Tit",
"category_page_result": "/index",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:percPage where jcr:path like '//Sites/Site1/%' and rx:page_title like '%Tit%' and rx:sys_contentpostdate >='2014/12/17' and rx:sys_contentpostdate <='2014/12/31' and ( rx:templateid='16777215-101-718') ",
"page_templates_list": "16777215-101-718",
"start_date": "12/17/2014",
"site_path": "//Sites/Site1"
}
"type": "percCategoryList"
}
Comments Form
{
"fields": {
"formdata": "{\"config\":{},\"fields\":[{\"label\":\"Title\",\"defaultValue\":\"\",\"type\":\"PercTitleFieldControl\"},{\"label\":\"URL\",\"defaultValue\":\"\",\"type\":\"PercURLFieldControl\"},{\"label\":\"User's name\",\"defaultValue\":\"\",\"type\":\"PercUserFieldControl\"},{\"label\":\"Comment box\",\"defaultValue\":\"\",\"type\":\"PercTextareaFieldControl\"},{\"label\":\"Email\",\"defaultValue\":\"\",\"type\":\"PercEmailFieldControl\"},{\"label\":\"Submit\",\"type\":\"PercSubmitButtonControl\"}]}",
"renderedform": "<script id='form-script' type='text/javascript'>jQuery(document).ready(function(){jQuery('form[name=commentForm]').validate({errorClass:'form-error-msg'})});</script><form name=\"commentForm\" method=\"post\" action=\"PERC_RV_COMMENT_FORM_ACTION\" accept-charset=\"ISO-8859-1\"><span class=\"form-title\"></span><input type=\"hidden\" name=\"perc_formName\" /><input type=\"hidden\" name=\"site\" value=\"PERC_RV_SITE_NAME\" /><input type=\"hidden\" name=\"pagepath\" value=\"PERC_RV_PAGE_PATH\" /><div class=\"field-row\"><div class=\"field-label-container\"><label for=\"field-title-input-container\">Title</label></div><div class=\"field-input-container\"><input type=\"text\" id=\"title\" name=\"title\" fieldmaxlength=\"255\" value=\"\" /></div></div><div class=\"field-row\"><div class=\"field-label-container\"><label for=\"field-url-input-container\">URL</label></div><div class=\"field-input-container\"><input type=\"text\" id=\"url\" class=\"url\" name=\"url\" fieldmaxlength=\"2000\" value=\"\" /></div></div><div class=\"field-row\"><div class=\"field-label-container\"><span class=\"perc-form-error-asterisk\">*</span><label for=\"field-users-name-input-container\">User's name</label></div><div class=\"field-input-container\"><input type=\"text\" id=\"users-name\" name=\"username\" class=\"required\" fieldmaxlength=\"255\" value=\"\" /></div></div><div class=\"field-row\"><div class=\"field-label-container\"><span class=\"perc-form-error-asterisk\">*</span><label for=\"field-comment-box-input-container\">Comment box</label></div><div class=\"field-input-container\"><textarea name=\"text\" class=\"required\" fieldmaxlength=\"4000\"></textarea></div></div><div class=\"field-row\"><div class=\"field-label-container\"><span class=\"perc-form-error-asterisk\">*</span><label for=\"field-email-input-container\">Email</label></div><div class=\"field-input-container\"><input type=\"text\" id=\"email\" name=\"email\" class=\"email required\" fieldmaxlength=\"255\" value=\"\" /></div></div><div class=\"field-row\"><input type=\"submit\" value=\"Submit\" /></div></form>"
},
"type": "percCommentsFormAsset",
}
Event
{
"fields": {
"body": "<div class=\"rxbodyfield\"><p>Summary Body</p></div>",
"displaytitle": "Event Title",
"callout": "Summary",
"end_time": "2014-12-31 00:00:00.0",
"location": "Location",
"start_time": "2014-12-01 00:00:00.0"
},
"type": "percEventAsset",
}
File Auto List
{
"fields": {
"asset_library_path": "//Folders/$System$/Assets/uploads/files",
"displaytitle": "File Auto List Title",
"end_date": "12/31/2014",
"title_contains": "Title ",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:percFileAsset where jcr:path like '//Folders/$System$/Assets/uploads/files/%' and rx:displaytitle like '%Title %' and rx:sys_contentcreateddate >='2014/12/08' and rx:sys_contentcreateddate <='2014/12/31'",
"start_date": "12/08/2014"
},
"type": "percFileAutoList",
}
Form Asset
{
"fields": {
"formuniquenamevalidator": null,
"formdata": "{\"config\":{\"name\":\"Form-Title\",\"title\":\"Form Title\",\"description\":\"Description\",\"processorType\":\"LocalServer\",\"processorURL\":\"\",\"successURL\":\"/index\",\"unencryptedSuccessURL\":\"/index\",\"encryptedSuccessURL\":\"-323485acfbb3acca\",\"errorURL\":\"/index\",\"unencryptedErrorURL\":\"/index\",\"encryptedErrorURL\":\"-323485acfbb3acca\",\"emailNotification\":true,\"mailTo\":\"mail@test.com\",\"unencryptedMailTo\":\"mail@test.com\",\"encryptedMailTo\":\"623456f5a6b41e924ef3d864d290dcb6\",\"mailSubject\":\"mail subject\",\"unencryptedMailSubject\":\"mail subject\",\"encryptedMailSubject\":\"-17d28f593deb5cb8e66c54bdfa694e02\"},\"fields\":[{\"label\":\"Descriptive text can be added by selecting the edit icon in the upper right.\",\"type\":\"PercTextFieldControl\"},{\"label\":\"Entry field label\",\"defaultValue\":\"Default text can be added to any text box.\",\"type\":\"PercEntryFieldControl\"},{\"label\":\"Submit\",\"type\":\"PercSubmitButtonControl\"}]}",
"formtitle": "Form Title",
"description": "Description",
"renderedform": "<script id='form-script' type='text/javascript'>jQuery(document).ready(function(){jQuery('#Form-Title').validate()});</script><form name=\"Form-Title\" method=\"post\" action=\"/perc-form-processor/form/\"><span class=\"form-title\">Form Title</span><input type=\"hidden\" name=\"perc_formName\" value=\"Form-Title\" /><input type=\"hidden\" name=\"perc_urlEncrypt\" value=\"true\" /><input type=\"hidden\" name=\"perc_successUrl\" value=\"-323485acfbb3acca\" /><input type=\"hidden\" name=\"perc_errorUrl\" value=\"-323485acfbb3acca\" /><input type=\"hidden\" name=\"perc_emnt\" value=\"623456f5a6b41e924ef3d864d290dcb6\" /><input type=\"hidden\" name=\"perc_emns\" value=\"-17d28f593deb5cb8e66c54bdfa694e02\" /><div class=\"field-row\"><span>Descriptive text can be added by selecting the edit icon in the upper right.</span></div><div class=\"field-row\"><div class=\"field-label-container\"><label for=\"field-entry-field-label-input-container\">Entry field label</label></div><div class=\"field-input-container\"><input type=\"text\" name=\"entry-field-label\" fieldmaxlength=\"255\" value=\"Default text can be added to any text box.\" /></div></div><div class=\"field-row\"><input type=\"submit\" value=\"Submit\" /></div></form>"
},
"type": "percFormAsset",
}
Raw html asset
{
"fields": {
"html": "<p>html text here</p>"
},
"type": "percRawHtmlAsset",
}
Image Auto List
{ "fields": { "asset_library_path": "//Folders/$System$/Assets/uploads/images", "displaytitle": "Image Auto List Title", "end_date": "12/31/2014", "title_contains": "Title contains", "query": "select rx:sys_contentid, rx:sys_folderid from rx:percImageAsset where jcr:path like '//Folders/$System$/Assets/uploads/images/%' and rx:displaytitle like '%Title contains%' and rx:sys_contentcreateddate >='2014/12/11' and rx:sys_contentcreateddate <='2014/12/31'", "start_date": "12/11/2014" }, "type": "percImageAutoList" }
Login Widget
{
"fields": {
"show_username": "showUsername",
"password_label": "Password",
"placeholder": null,
"not_logged_in_message": "Login",
"logged_in_message": "Welcome,",
"submit_label": "Submit",
"email_label": "Email"
},
"type": "percLoginAsset"
}
Page Auto List
{
"fields": {
"displaytitle": "Page auto list Title",
"feed_description": "feed description",
"end_date": "12/27/2014",
"title_contains": "T",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:percPage where jcr:path like '//Sites/Site1/%' and rx:resource_link_title like '%T%' and rx:sys_contentpostdate >='2014/12/08' and rx:sys_contentpostdate <='2014/12/27' and ( rx:templateid='16777215-101-718') ",
"enable_rss_feed": "Enable Rss feed",
"page_templates_list": "16777215-101-718",
"feed_title": "Rss feed title",
"feed_name": "rss-feed-title",
"start_date": "12/08/2014",
"site_path": "//Sites/Site1"
}
"type": "percPageAutoList",
}
Poll Widget
{
"fields": {
"pollTitle": "Poll title",
"pollUniqueName": "Poll-name",
"pollQuestion": "{\"question\":\"Poll Question\",\"answerType\":\"single\",\"answerChoices\":[\"Answer 1\",\"Answer 2\",\"Answer 3\"]}"
},
"type": "percPollAsset",
}
RSS
{
"fields": {
"placeholder": null,
"rss_url": "http://www.test.com"
},
"type": "percRssAsset",
}
Registration
{
"fields": {
"confirm_password_label": "Confirm password",
"password_label": "Password",
"submit_label": "Submit",
"email_label": "Email"
},
"type": "percRegistrationAsset",
}
Rich Text
{
"fields": {
"text": "<div class=\"rxbodyfield\"><p>rich text body</p></div>"
},
"type": "percRichTextAsset"
}
Secure Login
{
"fields": {
"buttonLabel": "Login",
"usernameLabel": "Username:",
"passwordLabel": "Password:",
"mainTitle": "Authentication required:"
},
"type": "percSecureLogin",
}
Tags
{
"fields": {
"displaytitle": "tags-title",
"end_date": "12/31/2014",
"tag_page_result": null,
"title_contains": "Title contains",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:percPage where jcr:path like '//Sites/Site1/%' and rx:page_title like '%Title contains%' and rx:sys_contentpostdate >='2014/12/08' and rx:sys_contentpostdate <='2014/12/31' and ( rx:templateid='16777215-101-718') ",
"page_templates_list": "16777215-101-718",
"start_date": "12/08/2014",
"site_path": "//Sites/Site1"
},
"type": "percTagList"
}
Text Auto List
{
"fields": {
"displaytitle": "Text Auto List Title",
"query": "select rx:sys_contentid, rx:sys_folderid from rx:PSWidget_SimpleText where jcr:path like '//Folders%'",
"max_results": "10"
},
"type": "percSimpleAutoList",
}
Delete an Asset
Functionality:
This REST call will allow you to delete an asset in your CM1 instance.
What you must know:
The folder path and name of the asset you want to delete.
Use Case:
You need to delete a page object.
How to execute:
Execute a DELETE request against the CM1 instance (http://myCM1:9992) with the Asset path /Assets/uploads and the asset name myasset.jpg.
Example:
DELETE http://myCM1:9992/Rhythmyx/rest/assets/by-path/Assets/uploads/myasset.jpg
Response:
{"message":"Deleted"}