Reference - Media Assets Management REST API 1.0.0 (Beta)

Document View

This API specification is available for download as an Open API 3.0 YAML file:

icm-media-assets-management-1x0x0.yaml

References

The following page lists available REST APIs for ICM 11 and their version dependencies:

Reference - Intershop Commerce Management 11 REST API

API Specification

Introduction

OpenAPI Version: 3.0.1

Media Assets Management Version: 1.0.0-beta

The Media Assets REST API allows to access files in the shared file system of Intershop Commerce Management that were uploaded via content upload.

API Versioning & Accept-Header

Media-type-based versioning is used to distinguish between different API versions. For requests to the Media Assets REST API v1, the REST client must set the following HTTP Accept header:

Accept: application/vnd.intershop.admin.mediaassets.v1+json

Changelog

Version 1.0.0

Introduced this REST API

Directories API

{loc}{forceTotal}/mediaassets/directories

GET: [BETA] Returns the subdirectories in the root content directory

Description

This operation returns subdirectories of the root content directory. Use the loc parameter to switch between the contents for different languages.

Java Method

public jakarta.ws.rs.core.Response com.intershop.application.rest.mediaassets.v1.capi.resource.MediaAssetsDirectoriesListResource.getDirectories_v1(java.lang.Integer,java.lang.Integer)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in query	limit	integer `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	integer `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The subdirectories in the root content directory.

DirectoriesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

400 - Bad Request - The path is invalid.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

404 - Not Found - The path could not be found.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

{loc}{forceTotal}/mediaassets/directories/{directoryName}/directories

GET: [BETA] Returns subdirectories in a directory.

Description

This operation returns subdirectories of the given directory. Use the loc parameter to switch between the contents for different languages. The path segment /directories/{directoryName} can be repeated multiple times to browse through the file tree, for example: mediaassets/directories/campaigns/directories/2023/directories/summersale/directories.

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in path	directoryName	string			Required \| The name of the subdirectory.
in query	limit	number `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	number `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The subdirectories in the directory.

DirectoriesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

400 - Bad Request - The path is invalid.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

404 - Not Found - The path could not be found.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

Directories & Files API

{loc}{forceTotal}/mediaassets

GET: [BETA] Returns directories and files in the root content directory

Description

This operation returns directories and files located in the root content directory. Use the loc parameter to switch between the contents for different languages. When using offset and limit, directories are listed before files.

Java Method

public jakarta.ws.rs.core.Response com.intershop.application.rest.mediaassets.v1.capi.resource.MediaAssetsListResource.getRootAssets_v1(java.lang.Integer,java.lang.Integer)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in query	limit	integer `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	integer `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The files and directories in the root content directory.

MediaAssetsRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

{loc}{forceTotal}/mediaassets/directories/{directoryName}

GET: [BETA] Returns the subdirectories and files in the directory

Description

This operation returns directories and files located in the specified subdirectory. Use the loc parameter to switch between the contents for different languages. When using offset and limit, directories are listed before files. The path segments /directories/{directoryName} can be repeated multiple times, to browse through the file tree, e.g. mediaassets/directories/campaigns/directories/2023/directories/summersale.

Java Method

public jakarta.ws.rs.core.Response com.intershop.application.rest.mediaassets.v1.capi.resource.MediaAssetsDirectoriesItemResource.getSubDirectoryAssets_v1(java.lang.Integer,java.lang.Integer)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in path	directoryName	string			Required \| The name of the subdirectory.
in query	limit	integer `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	integer `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The subdirectories and files in the directory.

MediaAssetsRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

400 - Bad Request - The path is invalid.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

404 - Not Found - The path could not be found.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

Files API

{loc}{forceTotal}/mediaassets/directories/{directoryName}/files

GET: [BETA] Returns the files in the directory (root or subdirectory)

Description

This operation returns files located in the specified directory. Use the loc parameter to switch between the contents for different languages. The path segment /directories/{directoryName} can be repeated multiple times to browse through the file tree, for example: mediaassets/directories/campaigns/directories/2023/directories/summersale/files.

Java Method

public jakarta.ws.rs.core.Response com.intershop.application.rest.mediaassets.v1.capi.resource.MediaAssetsFilesListResource.getFiles_v1(java.lang.Integer,java.lang.Integer)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in path	directoryName	string			Required \| The name of the subdirectory.
in query	limit	integer `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	integer `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The files in the directory.

FilesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

400 - Bad Request - The path is invalid.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

404 - Not Found - The path could not be found.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

{loc}{forceTotal}{loc}/mediaassets/files

GET: [BETA] Returns the files in the directory (root or subdirectory)

Description

Java Method

public jakarta.ws.rs.core.Response com.intershop.application.rest.mediaassets.v1.capi.resource.MediaAssetsFilesListResource.getFiles_v1(java.lang.Integer,java.lang.Integer)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in path	forceTotal	string		`true`	Flag indicating whether the calculation of the total number of elements should be forced, passed as an optional matrix parameter `;forceTotal=true`.
in path	loc	string	`en_US`		The locale ID (submitted as optional matrix parameter `;loc=<LOCALE>`). If omitted, the priority is as follows (from high to low): Locale ID parameter, user's default locale, site's default locale. The available locales depend on your individual Intershop Commerce Management installation. Use IANA language definitions for languages and regions and combine them using a underscore, e. g. `en_US`.
in query	limit	integer `int32`		`20`	Defines the maximum number of media assets in the response. The value cannot exceed the value configured by `intershop.backoffice.rest.maxAssetAmount` (default 50).
in query	offset	integer `int32`		`40`	Defines the starting position (number of elements to be skipped minus one).

Response

200 - OK - The files in the directory.

FilesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

400 - Bad Request - The path is invalid.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

401 - Unauthorized - The user could not be authenticated.

403 - Forbidden - The user is not allowed to access this resource.

404 - Not Found - The path could not be found.

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

Request and Response Object Schemata

DirectoriesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

{

"data":
array
An array of string literals. List of subdirectory names
"info":
object
A DirectoriesListInfoRO_v1 object. Optional
{
- "hasMoreElements":
  boolean
  Readonly | Flag that expresses if there more entries available. | Example: true
- "limit":
  integer
  Readonly | The limit of list entries to be shown. | Format: int32 | Example: 20
- "offset":
  integer
  Readonly | Excludes the first N items from the list. | Format: int32 | Example: 10
- "total":
  integer
  Readonly | The total amount of entries in the list. | Format: int32 | Example: 30
}
"messages":
array
Readonly | An array of FeedbackRO_v1 objects. List of messages regarding to the request (e.g. value adjustments).
[
FeedbackRO_v1: An error or piece of information related to the current request.
{
- "causes":
  array
  An array of FeedbackCauseRO_v1 objects. A collection of errors/warnings/infos that caused the feedback.
  [
  FeedbackCauseRO_v1: A representation for the common feedback information.
  {
  "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
  "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
  "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
  "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
  }
  ]
- "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
- "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
- "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
- "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
- "level":
  string
  The level of the feedback. | Example: ERROR | Possible Values: INFOWARNERROR
- "status":
  string
  The HTTP status code that is applicable to this problem. | Example: 422
}
]

}

FeedbackContainerRO_v1 application/vnd.intershop.admin.mediaassets.v1+json

{

"messages":
array
Readonly | An array of FeedbackRO_v1 objects. List of messages regarding to the request (e.g. value adjustments).
[
FeedbackRO_v1: An error or piece of information related to the current request.
{
- "causes":
  array
  An array of FeedbackCauseRO_v1 objects. A collection of errors/warnings/infos that caused the feedback.
  [
  FeedbackCauseRO_v1: A representation for the common feedback information.
  {
  "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
  "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
  "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
  "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
  }
  ]
- "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
- "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
- "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
- "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
- "level":
  string
  The level of the feedback. | Example: ERROR | Possible Values: INFOWARNERROR
- "status":
  string
  The HTTP status code that is applicable to this problem. | Example: 422
}
]

}

FilesRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

{

"data":
array
An array of string literals. List of file names
"info":
object
A FilesListInfoRO_v1 object. The optional information about the response object. All values are also optional.
{
- "files":
  array
  Readonly | An array of FileInfoRO_v1 objects. Further information about the files
  [
  FileInfoRO_v1: Information about a file
  {
  "name":
  string
  Readonly | Name of the file | Example: image.jpg
  "uri":
  string
  Readonly | URI to the image | Example: /INTERSHOP/static/WFS/inSPIRED-Site/-/inSPIRED/en_US/image.jpg
  "descriptor":
  string
  Readonly | The image content descriptor | Example: inSPIRED:/image.jpg
  }
  ]
- "hasMoreElements":
  boolean
  Readonly | Flag that expresses if there more entries available. | Example: true
- "limit":
  integer
  Readonly | The limit of list entries to be shown. | Format: int32 | Example: 20
- "offset":
  integer
  Readonly | Excludes the first N items from the list. | Format: int32 | Example: 10
- "total":
  integer
  Readonly | The total amount of entries in the list. | Format: int32 | Example: 30
}
"messages":
array
Readonly | An array of FeedbackRO_v1 objects. List of messages regarding to the request (e.g. value adjustments).
[
FeedbackRO_v1: An error or piece of information related to the current request.
{
- "causes":
  array
  An array of FeedbackCauseRO_v1 objects. A collection of errors/warnings/infos that caused the feedback.
  [
  FeedbackCauseRO_v1: A representation for the common feedback information.
  {
  "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
  "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
  "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
  "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
  }
  ]
- "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
- "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
- "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
- "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
- "level":
  string
  The level of the feedback. | Example: ERROR | Possible Values: INFOWARNERROR
- "status":
  string
  The HTTP status code that is applicable to this problem. | Example: 422
}
]

}

MediaAssetsRESTResponse_v1 application/vnd.intershop.admin.mediaassets.v1+json

{

"data":
object
A MediaAssetsDataRO_v1 object. The core data of the response object.
{
- "directories":
  array
  Readonly | An array of string literals. List of subdirectory names
- "files":
  array
  Readonly | An array of string literals. List of all files in this directory
}
"info":
object
A MediaAssetsListInfoRO_v1 object. The optional information about the response object. All values are also optional.
{
- "files":
  array
  Readonly | An array of FileInfoRO_v1 objects. Further information about the files
  [
  FileInfoRO_v1: Information about a file
  {
  "name":
  string
  Readonly | Name of the file | Example: image.jpg
  "uri":
  string
  Readonly | URI to the image | Example: /INTERSHOP/static/WFS/inSPIRED-Site/-/inSPIRED/en_US/image.jpg
  "descriptor":
  string
  Readonly | The image content descriptor | Example: inSPIRED:/image.jpg
  }
  ]
- "hasMoreElements":
  boolean
  Readonly | Flag that expresses if there more entries available. | Example: true
- "limit":
  integer
  Readonly | The limit of list entries to be shown. | Format: int32 | Example: 20
- "offset":
  integer
  Readonly | Excludes the first N items from the list. | Format: int32 | Example: 10
- "total":
  integer
  Readonly | The total amount of entries in the list. | Format: int32 | Example: 30
}
"messages":
array
Readonly | An array of FeedbackRO_v1 objects. List of messages regarding to the request (e.g. value adjustments).
[
FeedbackRO_v1: An error or piece of information related to the current request.
{
- "causes":
  array
  An array of FeedbackCauseRO_v1 objects. A collection of errors/warnings/infos that caused the feedback.
  [
  FeedbackCauseRO_v1: A representation for the common feedback information.
  {
  "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
  "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
  "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
  "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
  }
  ]
- "code":
  string
  Required | A unique identifier for this particular occurrence of the problem (may be used for localization on client-side). | Example: product.name.required.error
- "message":
  string
  Required | A human readable message in the request's locale. | Example: The product name must be specified.
- "parameters":
  array
  An array of object literals. A map of several parameters that are used to assemble the message.
- "paths":
  array
  An array of string literals. A collection of JSON paths to the associated entities. Unless otherwise specified, this always refers to the request entity. | Documentation: https://github.com/json-path/JsonPath | Example: ["\"$.name (position: 1)\""]
- "level":
  string
  The level of the feedback. | Example: ERROR | Possible Values: INFOWARNERROR
- "status":
  string
  The HTTP status code that is applicable to this problem. | Example: 422
}
]

}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.