Skip to main content
Version: v1

Domains

Domains are the primary object in the system for managing CDN services for websites.

Domain Management​

Domain Statuses​

The status field of the domain object (domain.status) is used to determine the current state of a domain.

Possible values:

  • OK (CDN is enabled for the domain)
  • DISABLED (CDN is disabled for the domain)
  • BLOCKED (domain is blocked)
  • CHECKING_NS_LIST (domain delegation is being verified)
  • DOMAIN_NOT_DELEGATED (domain is not delegated)
  • CREATING_SSL_CERT (SSL certificate is being issued for the domain)
  • SSL_CERT_CREATING_ERROR (error issuing SSL certificate for the domain)
  • UPDATING_DNS_RECORDS (updating records on PDNS)
  • UPDATING_DNS_RECORDS_ERROR (error updating records on PDNS)

Creating a Domain​

Domain creation is synchronous, and a domain object is created in the system.

note

CDN service is inactive immediately after domain creation. Domain status is DISABLED.

A cdn_domain field is generated for each domain. This is the domain name from which static content will be distributed from caching servers. If the created domain type is cname, the object will generate and populate the cname_url field. This is a domain name that, if necessary, can be specified as content in the CNAME record in the client's DNS.

Updating a Domain​

Domain updates are synchronous, and the domain object is updated in the system. Available fields of the corresponding API method are used for making changes.

Working with TLS/SSL Certificates​

After creating a domain, users can automatically issue a free certificate from Let's Encrypt or upload their own. To issue a certificate, use the issue_cert method. This creates a task of type ISSUE_CERT. The free certificate will be automatically renewed every 60 days. Automatic renewal can be disabled at the application level. To upload a custom certificate, use the upload_ssl_cert method. This method works synchronously. Certificate updates/uploads are allowed whether the CDN service is enabled or disabled.

Uploading a certificate for domains of type delegated​

When uploading a certificate for a domain of type delegated, the system checks that the certificate is issued for the domain name domain.name specified when creating the domain object. The domain_name field of the API method is not involved in validation.

info

The value of the domain.cdn_domain field for a domain of type delegated is always equal to the value of the domain.name field.

Usage example:

  • create a domain with the name "example.com" and type delegated
  • upload a certificate
  • among the list of domain names in the uploaded certificate (Subject Alternative Name), "example.com" or "*.example.com" must be present
  • enable CDN for the domain
  • after the DNS server cache is updated, encryption of requests to "example.com" will be performed using the uploaded certificate

Uploading a certificate for domains of type cname​

To upload a certificate for a domain of type cname, you need to specify the desired domain name in the domain_name field. This is the domain name through which requests will be routed via CDN servers. It cannot be the same as domain.name .

warning

After successfully uploading the certificate, the cdn_domain field of the domain object will be updated.

Usage example:

  • create a domain with the name "example.com" and type cname
  • the cname_url field will be automatically filled for the domain, for example, "d121.static-clients.arviol.com"
  • upload a certificate, specifying in the domain_name field the domain name from which the site's static content will be served, for example, "cdn.example.com"
  • among the list of domain names in the uploaded certificate (Subject Alternative Name), "cdn.example.com" or "*.example.com" must be present
  • after successfully uploading the certificate, the cdn_domain field of the domain object will be updated to "cdn.example.com"
  • enable CDN for the domain
  • in the DNS hosting settings, add a CNAME record: name="cdn.example.com", data="d121.static-clients.arviol.com"
  • after DNS cache is updated, requests to "cdn.example.com" will be routed through the CDN servers

Enabling CDN Service for a Domain​

To enable the service, use the API method enable_cdn_for_domain. Upon successful execution, the system creates an ENABLE_CDN task. If the service is already enabled for the domain, the method will return an appropriate error code. One of the steps in enabling the service is issuing a new SSL/TLS certificate or renewing the current one if it has expired. If a custom certificate was uploaded before enabling, no actions are taken with it. After successful task completion, the domain status changes to OK - the service is active. The domain name for retrieving static content from cache servers:

  • domain.name - for delegated domains (delegated)
  • domain.cname_url - for non-delegated domains (cname)

Disabling CDN Service for a Domain​

To disable the service, use the API method disable_cdn_for_domain. Upon successful execution, the system creates a DISABLE_CDN task. If the service is already disabled for the domain, the method will return an appropriate error code. After successful task completion, the domain status changes to DISABLED - the service is disabled.

WAF​

waf objects are secondary to domains. A set of API methods is implemented for managing waf.

Object structure:

{
    "id": 1,
    "domain_id": 1,
    "sec_rule_engine": "detection_only",
    "paranoia_level": 1,
    "executing_paranoia_level": 1,
    "critical_anomaly_score": 5,
    "error_anomaly_score": 4,
    "warning_anomaly_score": 3,
    "notice_anomaly_score": 2,
    "in_score_threshold": 5,
    "out_score_threshold": 4,
    "sampling_percentage": 100
}

Exporting WAF Logs​

To retrieve WAF logs for a domain, use the API method get_waf_logs.

Parameters must include the start time (inclusive) and end time (exclusive) for the query. Additional parameters include limit - the maximum number of logs expected in the response, and offset - the offset for implementing pagination.

The method returns an object containing total_count - the total number of records in storage for the specified dates, and logs - an array of JSON records with error data.

note

The total_count value does not match the length of the logs array.

For example, if there are 2000 records in storage (ids=1-2000) for the specified dates, and the request specifies limit = 100, offset = 100, the response will contain: total_count = 2000, logs.length = 100 (id=101-200).

Locations​

Up to 10 secondary locations objects can be added for each domain. A set of API methods is implemented for managing locations.

Object structure and default field values:

{
    "id": 1,
    "domain_id": 1,
    "name": "/static/",
    "type": "matching",
    "headers": [
        {
            "key": "Accept-Encoding",
            "value": "gzip, deflate, br"
        }
    ],
    "request_headers": [
        {
            "key": "X-Origin-Routing",
            "value": "beta"
        }
    ],
    "cors_headers": {
        "access_control_allow_origin": [
            "*"
        ],
        "access_control_expose_headers": [
            "*"
        ],
        "access_control_max_age": 600,
        "access_control_allow_credentials": true,
        "access_control_allow_methods": [
            "DELETE"
        ],
        "access_control_allow_headers": [
            "*"
        ]
    }
}

headers — an array of response headers that the CDN adds before returning content to the user. Each element contains a key and value, allowing you to fine-tune caching behavior, security policies, or diagnostic markers.

request_headers — an array of headers that the CDN forwards to the origin when fetching the original resource. Each element contains a key and value, making it possible to send routing hints, A/B test parameters, or other operational metadata to backend systems.

Access Restrictions​

Domains support access restriction functionality, managed by the domain.access_params object. Object structure:

{
    "disallowed_country_codes": [
        "RU",
        "BY"
    ]
}

The disallowed_country_codes field lists country codes for which client requests will receive a 403 Forbidden error response. Country codes must follow two-letter designations per ISO 3166 Alpha-2.

Signed URLs​

The fields signed_url_enabled and signed_url_key of location objects are responsible for enabling and disabling the access restriction feature to site sections via signed URLs. You can enable or disable this feature by updating the location object. When the feature is enabled, access to the corresponding site section is granted only to holders of signed URLs. The client is responsible for generating these signed URLs.

Below are recommendations for domain management.

Initial Setup:​

  1. Create a domain
  2. Upload/issue a certificate if needed
  3. Add locations list if needed
  4. Add waf if needed
  5. Enable CDN service

Domain Update:​

  1. Make all desired configuration changes
  2. Call the domain update API method
  3. Make changes to secondary objects (no need to call the domain update method)

API Methods​

Domains​

Certificates​

Locations​

WAF​