Description of work and documentation

Link to file

The uploaded file can be accessed via a link in a specific format:
http(s)://[domain]/cdn/files/{file_id}/{filename}.{extension}

Description of the link format. 1. HTTP scheme You can use the protocol on your own: http or https
2. domain Default domain is cdn.tinycdn.cloud. You can use CNAME record to use your domain. To do this, you must:

• For your domain, create a CNAME record pointing to cdn.tinycdn.cloud
• Specify your domain in the appropriate field to edit the project in your account

3. file_id This is the integer ID of the uploaded file. 4. filename The display name of the file, can be any for Clean URL 5. extension Displayed file extension, can be any for Clean URL
Header Content-Type is given based on the file extension when it is loaded

Query Parameters in the file link

The link to the file can, and sometimes is necessary, to supplement the query parameters (passed after ? in link)

Available query parameters
1. token This parameter transfers the file access token if the file is accessible by token.
The need for it is determined when uploading a file. It can be loaded with flag private - then without the correct token the server will give an error 403 (Forbidden)
Also, the privacy of a file can be overridden to modify it, more in the section on content processing rules.
2. format for images only Forces image format conversion. Valid values: png, gif, jpeg, webp, avif
3. download Sends to browser http header Content-Disposition: attachment, what causes the browser to download the file, even if he can display this type of content
4. width & height for images only Parameters set the required width and height of the image, respectively.
If you specify width and height, it will be resize for the specified size. If you specify only one parameter, then the second will be calculated with the proportions
5. quality for images only Desired compression level, 0 - minimum, 100 - maximum. Affects file size

Content processing rules (File Modifications) for images only

When a file is uploaded, the group is specified. For upload via the widget default group is public_upload
The group can be assigned processing rules.

File modifications storage

• Stores modifications for which exact match is found for all parameters: now its width and height, and parameter format does not affect the search rule for modification
• For example, you can make a rule with the key product_image and parameters width: 100, height: 100. And another rule with a key product_image and parameters width: 200, height: 200.
• When uploading a file by API, it can assign a set of rules, via argument rule_key. For example, rule_key: product_image
• Then, when requesting the file 100x100 and 200x200, these files will be saved to the file system, which will speed up the processing of the following requests of the same file
• And if you request an arbitrary size, the image will be resized based on the source file and will NOT be saved to the file system.
• Modifications can overwrite the file access method. For example, the original is available only by token, and 100x100 is available to all
• Modifications are kept only for strict rules. For partial modification rules, the resulting images are not stored in the file system.

Determining the appropriate modification

• Wins the first rule that fits all the specified conditions, and not the one that fits best.
• The order of processing rules (suitable / not suitable) is specified manually when creating rules
• First, all rules that require strict compliance are processed.
• Then all the rules are processed that are quite partial.
• You can create a partial match rule, without any conditions - all requests will be caught (if necessary, of course)
• for rules of full compliance, you can check the compliance width and height (you can specify only one of the keys)
• for partial matching rules, you can check compliance min_width, max_width, min_height and max_height (all keys are optional)

Initial modification (on file upload)

Correct configuration of the initial modifications will help to optimize the size of the occupied disk space and make further work with files more comfortable. The rules for this modification are wrapped in a key first. If a suitable rule is found, it will be changed when the image is loaded.
The following settings are supported:

• first.width: image width
• first.height: image height
• first.max_width: max image width
• first.max_height: max image height
• first.format: image format

Sample json code to describe a rule, that the uploaded files should be limited in size and converted to webp

{
    "first": {
        "max_width": 2000,
        "max_height": 2000,
        "format": "webp"
    }
}

WaterMark in File Modifications

• if the rules specify the watermark setting, it is mandatory to impose
• the watermark file itself must have been previously uploaded to CDN with the file type "image"

Sample json code to describe a WaterMark

"watermark": {
    "id": 10,
    "position": {
        "orientation": "right/bottom",
        "x": 10,
        "y": "20%"
    }
}

1. Key id - file id on cdn with watermark. Must be type image
2. The position key determines the offset of the watermark overlay.
3. The orientation key determines where the countdown comes from. May have the following values

• left/top
• left/center
• left/bottom
• center/top
• center/center
• center/bottom
• right/top
• right/center
• right/bottom

Key x - additional horizontal offset. With left or center orientation, the offset goes to the left. With the orientation right, the offset goes to the right
Key y - additional vertical offset. With top or center orientation, the offset goes down. With the bottom orientation, the offset goes up
The x and y key values can be negative. Specifies the number (pixels), or a string like "5%" - as a percentage of the size of the original image. Default 0. Value examples: 10, -20, "5%"

Examples of position processing, for a picture 200x200 and a watermark 40x40

{
    // right indent = 10px, bottom = 20% = 40px
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "right/bottom",
            "x": 10,
            "y": "20%"
        }
    }
}

{
    // right indent = 10px
    // top indent = (200 - 40) / 2 = 80px
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "right/center",
            "x": 10
        }
    }
}

{
    // left indent = centered and shifted by -10px = ((200 - 40) / 2) -10 = 70px
    // top indent = 0
    "watermark": {
        "id": 10,
        "position": {
            "orientation": "center/top",
            "x": -10
        }
    }
}

API

CDN have GraphQL API. Each client can use it to automate their work or for other reasons.

We made the documentations and composer package.

Errors when viewing files

Errors are given via HTTP status codes

• View the protected file without the correct token = 403 (Forbidden)
• View file by ID if not found = 404 (Not Found)