The External File Library - API documentation


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.

External

 

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.
Was this article helpful?
0 out of 0 found this helpful