Create a Distribution

Prerequisite: Only contract administrators, owners, and users with accessAndManageCdn privilege can create and manage CDN distributions via the API. You can also set user privileges in the DCD. For more information, see Set User Privileges.

To create a CDN distribution, perform a POST request.

Endpoint

Use the following endpoint to create a CDN distribution: https://cdn.de-fra.ionos.com/distributions.

Request

curl --X \  
--request POST 'https://cdn.de-fra.ionos.com/distributions' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO' \
--header 'Content-Type: application/json' \
--data '{
    "properties": {
        "domain": "example.com",
        "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
        "routingRules": [
            {
                "scheme": "http/https",
                "prefix": "/api",
                "upstream": {
                    "host": "server.example.com",
                    "caching": true,
                    "waf": true,
                    "geoRestrictions": {
                        "blockList": [
                            "CN",
                            "RU"
                        ]
                    },
                    "rateLimitClass": "R10"
                }
            }
        ]
    }
}
}'

Request Body Parameters

Below is the list of mandatory body parameters:

Body Parameters	Type	Description	Example
domain	string	The domain name for the CDN distribution.	example.com
scheme	string	Choose whether to allow http, https, or http/https protocol.	http/https
prefix	string	A prefix to match the beginning segment of the URL path and apply routing rule.	/api
host	string	An upstream host name that handles requests if data not cached in the CDN edge server.	server.example.com
caching	boolean	If enabled, CDN caches the data from the upstream host.	true
waf	boolean	If enabled, protects the upstream host.	true
rateLimitClass	string	Limits the number of incoming requests per IP.	R10

Request Header Parameters

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters	Required	Type	Description
Authorization	yes	string	The Bearer token enables requests to authenticate using a JSON Web Token (JWT). From the DCD, Generate authentication token.
Content-Type	yes	string	Set this to application/json.

Response

201 Successful operation

{
  "id": "9ba15778-16c4-543c-8775-e52acf4853f5",
  "type": "distribution",
  "href": "/distributions/9ba15778-16c4-543c-8775-e52acf4853f5",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "publicEndpointIpv4": "1.2.3.4",
    "publicEndpointIpv6": "2001:db8::ff00:42:8329",
    "state": "AVAILABLE",
    "message": "In progress."
  },
  "properties": {
    "domain": "example.com",
    "certificateId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
    "routingRules": [
      {
        "scheme": "http/https",
        "prefix": "/api",
        "upstream": {
          "host": "server.example.com",
          "caching": true,
          "waf": true,
          "geoRestrictions": {
            "blockList": [
              "CN",
              "RU"
            ]
          },
          "rateLimitClass": "none"
        }
      }
    ]
  }
}

Result: The CDN distribution is successfully created; the id and other details of the created distribution are provided in the response.