Media administation
Fragestellungen:
- How to manage media?
Beschreibung:
Whenever you want to use media in TYRIOS, you need to upload the media into the media system. This has several reasons:
- Media in the media system is automatically analyzed and optimized. That means especially for images and videos, that the files are automatically optimized in dimensions, size and quality.
- Media is automatically sanitized. This does not only include mime and content analysis, but also an automatic virus check.
To use media in TYRIOS you thus need to upload media, which is automatically analyzed. The media library supports a parent-child system to realize a directory structure. There is a root object with ID 1 and every object must at least provide this object as parent.
Authentication
The API endpoints of TYRIOS are only available for authorized users. Therefore, the user must be authenticated. There are two different authentication types:
- Authentication by BASIC authentication. The user account must have an activated REST API token. You need to send an appropriate BASIC authentication header.
- Authentication by mobile app registration. You need to send an appropriate app registration token.
Required rights
To use this API, you need to have user credentials with media management rights. If you don't have these rights, you will get a 403 error code. The API is not available for external users without credentials.
Data structure
Media is managed by the MediahelperFile data structure. A MediahelperFile can have different types, indicated by the mediaType:
- 1=image,
- 2=video,
- 3=sound,
- 4=document,
- 5=zip,
- 6=directory
Depending of the type, TYRIOS automatically optimizes the media for further usage.
Add new directory
To add a new directory, you need to create a PUT request to following endpoint
https://[instance-domain]/MediaManagement/service/media/[parentID]
As payload, you need to send:
Payload:
{ "name": "DirectoryName", ["returnIfExistent": true] }
Return value: mediahelper file for the directory. If the path already exists and if you have added the returnIfExistent parameter in your payload, the directory mediahelper scruct is provided, else an exception is provided.
Example with cURL:
adding a directory to root with name "directory"
curl -u admin:restSecret -X PUT -d '{"name":"directory"}' https://[domain]/service/MediaManagement/media/1
Return value as example
{
"id":777,
"fileName":"directory",
"mediaType":"6",
"detailFormat":null,
"filePath":"\/\/",
"alternativeText":null,
"fileDescription":null,
"uploadTime":0,
"MediahelperFileDescendant":null,
"parentID":1,
"UserData":1,
"securityLevel":"1",
"fileHash":"etcyjs3bmcqi9wzsfe5zsy0og20ordpshd99c69yc7z8a9zx00",
"version":1,
"width":null,
"height":null,
...
}
Please keep in mind, that in TYRIOS the data structure is dynamic as TYRIOS is an aspect oriented system. So there might be further fields in your installation.
Add new media
To add a new media file, you need to upload the media in a multipart/form-data encoded format. The system supports one file upload only so that you can retrieve the corresponding IDs
Endpoint for the POST request
https://[instance-domain]/service/MediaManagement/service/media/[parentID]/newFile
Payload example using cURL:
curl -u admin:restSecret -X POST -F "file=@/path/to/file.jpg" https://[instance]/service/MediaManagement/media/777/newFile
It is possible to specify a security level in your payload. Therefore, you must provide an option field for securityLevel in json format
curl -u admin:restSecret -X POST -F "file=@/path/to/file.jpg" -F "options={\"securityLevel\":3};type=application/json" https://[instance]/service/MediaManagement/media/777/newFile
The system provides you the mediahelper file as response.
Change the security level
TYRIOS supports three security levels:
- 1=public
- 2=private, but shareable (by using a hash)
- 3=private and not shareable, controled by user rights
To change the security level, you need to sent a POST requeset to following URL
https://[instance-domain]/service/MediaManagement/service/media/[mediaID]/securityLevel
As Payload, you need to provide following data struct:
{ "securityLevel": 2 }
As response, the system will provide the media as JSON struct.
Delete media
To delete a media, you need to send a DELETE request to the endpoint:
https://[instance-domain]/service/MediaManagement/service/media/[mediaID]
The system automatically verifies if the file is in use (except for editor usage) and will provide a corresponding error message, if this is the case