The External File Library is an exciting new feature that allows partners to use files and images from external data sources in the Editor. An external data source could be the customer’s own file library, potentially from Google Drive.
With the External File Library, you will have increased control over your data outside of the Editor and give more freedom on what files and images are potentially available to fulfilment agents or clients. It will also be an option to use an Author Tag to provide copyright information on the images.
This functionality requires API.
Technical requirements/integration part
To use the External Filesystem Library, partners need its own Application Program Interface (API) endpoint returning the external filesystem data/files.
The API provides a gateway to access the partner’s own filesystem, while on the Mono Solutions editor. Our module also allows integrate it and move files across systems with ease and while maintain the site integrity.
EFL provides a one direction file copy and navigation, from the external system to Mono’s own internal filesystem, used by our Editor Tool and sites while not providing any kind of synchronization of data if changes happen on the partner’s site. If a file changes on the partner’s filesystem, such change will not be replicated on Mono’s side unless the new updated file is moved again using EFL.
If there’s any further questions, please reach out to our Support.
API definition notes
The response from the API providing list of available contents needs to follow specific schema to work correctly with the website editor. To identify Mono users at partner’s API level a JSON Web Token (JWT) is generated by us. The specification of fields and structures of headers, responses and tokens is given below.
1. Endpoint
Partner needs to provide an endpoint URL, where available files/directories can be listed from. The endpoint needs to accept GET requests and implement a caller identification based on JWT signature verification.
The endpoint should also expect the following query parameters:
{
"path": "/cats_images",
"page": {
"number": 1,
"offset"?: 1,
"limit": 10
},
"filter": "orange",
"order": {
"by": "name",
"direction": "asc"
}
}
Field name | Data type | Description |
path | string | Path of the directory to list |
page.number | number | Page number, if request paginated |
page.offset | number | Page item offset, if request paginated. Optional |
page.limit | number | Page limit of items, if request paginated |
filter | string | Filter content by provided string. Both “Files” and “Directories” |
order.by | string | Order content by file type (type), size or file name (name) |
order.direction | string | Order content ASC or DESC |
2. Authentication token
The authentication token is a signed JWT bearer token hashed with HS256 (HMAC with SHA-256). Salt used for hashing can be provided either by the partner or Mono. Generated bearer token is used as authentication header value - "Authentication ": "Bearer <JWT>". This is the only header we add on top of the default ones. The specification of the JWT fields and values is given below:
a. Field Reference
Field name | Data type | Description |
iss | string | Issuer name. “MS” value is used as the identification of Mono. |
iat | number | Time when token was generated/issued. |
exp | number | Expiration time of the token. By default, its value is calculated as follows: iat+60s |
aud | string | Mono site ID in Mono system. |
sub | string | Mono account ID in Mono system. |
b. JSON example
{
"iss": "MS",
"iat": 1678730616,
"exp": 1678731863,
"aud": "1234567",
"sub": "123456"
}
3. Successful response
If the Mono user was authenticated in partner’s system, it should respond with one of the successful responses status codes – by default 200. The response can contain information about returned contents partitioned into pages and must contain a collection of available contents. Expected data types and values are described in detail by the end of this section. The schema should follow the structure as below:
{
"links"?: {
"self": "example.com/page=2",
"previous": "example.com/page=1"
"next": "example.com/page=3",
"count": "100"
},
"data": [
{
"type": "files",
"collection": [
{
"type": "file",
"id": "0oc4d388",
"attributes": {
"url": "https://example.com/cat_01.jpg",
"name": "Cat 01",
"filename": "cat_01.jpg",
"mimetype": "image/jpg",
"size": 100,
"thumbnail": "https://example.com/cat_01_thumb.jpg",
"author": "A really big Cat"
}
}
]
},
{
"type": "directories",
"collection": [
{
"type": "directory”,
"id": "1wc6y482",
"attributes": {
"path": "/cats_images",
"name": "Cats images",
"size": 1000
}
}
]
}
]
}
4. Errored response
In case of an error on the partner’s API side, a corresponding and informative error message should be returned. It is important to use standard status codes (4xx and 5xx) for respective issues. The details of each field in error response are described by the end of this section. The schema for it is given below:
{
"error": {
"code": "BadRequest",
"message": "The requested content is missing.",
"target"?: "File",
"details"?: [
{
"code": "BadRequest",
"target": "File",
"message": "File metadata missing. Error 112233"
}
]
}
}
5. Data fields specification
Response code | Field path | Data type | Description |
200 OK |
links | object | Optional field indicating paginated response. |
links.self | string | Pagination; Current page path. | |
links.previous | string | Pagination; Previous page path. Empty if there is no previous page. | |
links.next | string | Pagination; Next page path. Empty if there is no next page. | |
links.count | string | Number of total items being paginated | |
data | array | Array of custom contents offered by the partner. | |
data[0].type | string | Parent-category name of the content. “Files” or “Directories” | |
data[0].collection | array | Array of contents variations. | |
data[0].collection[0].type | string | Content’s variant name. “File” or “Directory” | |
data[0].collection[0].id
|
string | UUID or Unique HASH of the content | |
data[0].collection[0].attributes.name | string | Sanitized name of the content variation. Used for both “Files” and “Directories” | |
data[0].collection[0].attributes.size
|
string | Size of the content variation in bytes. Used for both “Files” and “Directories”. Note: in “Directories” it can also be sent as 0, if no information available. | |
data[0].collection[0].attributes.path
|
string | Path of the directory. Format: /path_1/path_2/... | |
data[0].collection[0].attributes.url
|
string | URL of the file to be used when copying from the external filesystem to Mono’s system. Used only on “Files”. | |
data[0].collection[0].attributes.filename
|
string | System file name. E.g.: image_01.jpg | |
data[0].collection[0].attributes.mimetype
|
string | File mime type. E.g.: image/jpg | |
data[0].collection[0].attributes.thumbnail
|
string | URL to the file thumbnail. This URL will be used to show the file thumbnail on EFL interface. It should be a reduced version of the original. Suggestion: 200x200 with no more than 100bytes. | |
data[0].collection[0].attributes.author
|
string | Author of the file, for copyright purposes. The author will be added to the file element when rendered on the site. | |
400 BadRequest
Or any other 4xx and 5xx code. |
code | string | Status code meaning. Any 4xx code should reflect its corresponding meaning. 400 is the default. |
message | string | Descriptive message of the error. | |
target | string | Optional, describes the target that originated the error. | |
details | array | Optional, an array of additional, partner-specific errors. | |
details[0].code | string | Status code meaning. Any 4xx code should reflect its corresponding meaning. 400 is the default. | |
details[0].target
|
string | Describes the target that originated the additional error. | |
details[0].message
|
string | Descriptive message of the additional error. |