Origins

The servers the edge forwards clean traffic to, how it spreads load across them and when it takes one out of rotation. See API access.

Endpoints

Method	Path	Key	Purpose
GET	/services/{fqdn}/origins	read	List the origins of a vService
POST	/services/{fqdn}/origins	write	Add an origin
DELETE	/services/{fqdn}/origins/{origin_name}	write	Remove an origin
PUT	/services/{fqdn}/origins/{origin_name}	write	Replace an origin

GET /services/{fqdn}/origins

Returns: 200, list of Origin

Answer 200

[
  {
    "name": "origin-1",
    "address": "192.0.2.10",
    "port": 443,
    "tls": true,
    "ssl_verify": true,
    "weight": 100,
    "maxconn": 100
  }
]

POST /services/{fqdn}/origins

Parameter	In	Meaning
Idempotency-Key	header	Makes a retry return the first result; up to 128 characters

Body: Origin
Returns: 201, Origin

Request

{
  "address": "192.0.2.13",
  "port": 443
}

Answer 201

{
  "name": "origin-2",
  "address": "192.0.2.13",
  "port": 443,
  "tls": true,
  "ssl_verify": true,
  "weight": 100,
  "maxconn": 100
}

DELETE /services/{fqdn}/origins/{origin_name}

Returns: 204, no body

PUT /services/{fqdn}/origins/{origin_name}

Body: Origin
Returns: 200, Origin

Request

{
  "name": "origin-1",
  "address": "192.0.2.14",
  "port": 443
}

Answer 200

{
  "name": "origin-1",
  "address": "192.0.2.14",
  "port": 443,
  "tls": true,
  "ssl_verify": true,
  "weight": 100,
  "maxconn": 100
}

Fields

Origins have the endpoints above and are also origins in PATCH /services/{fqdn}. backend and these fields are part of the service:

Field	Type	Notes
origin_host	string	up to 253 characters; may be null; Host header sent to your origins for requests to the FQDN; aliases keep their own. Also the Host of the health check and the default TLS server name. Default: the FQDN
origin_sni	string	up to 253 characters; may be null; TLS server name sent to TLS origins without their own sni. Default: origin_host, else the FQDN
origin_kind	string	one of dynamic, static; may be null; static: your origin is a bucket or file server, and the edge replaces its 403 and 404 answers with the branded error pages. dynamic: its answers pass unchanged

Origin

Field	Type	Notes
name	string	up to 64 characters; may be null; Omit it and the server names the origin origin-1, origin-2, ...; the name is in the response and is what PUT and DELETE take
address (required)	string	IPv4 address, IPv6 address or hostname. Private and reserved addresses are refused, also when a hostname resolves to one
port	integer	1–65535; default 443; Port on the origin. Requests to an extra HTTP port go to the same port number instead
tls	boolean	default true; Connect to the origin with TLS
ssl_verify	boolean	default true; Verify the origin's certificate against the public certificate authorities; with tls only
sni	string	up to 253 characters; may be null; TLS server name for this origin, also the name its certificate is checked against. Default: origin_sni, else origin_host, else the FQDN
weight	integer	0–256; default 100; Share of requests relative to the other origins, 0 to 256; 0 sends none. Also the share of new UDP flows
maxconn	integer	1–65535; default 100; Connections each edge opens to this origin at most. Further requests queue, up to 4 times this per origin and for at most 2 s; beyond either they get 503. With a sensitivity set, a learned value replaces it once measured

Backend

Field	Type	Notes
algorithm	string	one of roundrobin, leastconn, source, uri; default "roundrobin"; roundrobin: in turn, by weight. leastconn: the origin with the fewest open connections. source: by client address, so a client stays on one origin. uri: by request path, so a path stays on one origin
health_check	HealthCheck	Health check of the origins

HealthCheck

Field	Type	Notes
method	string	one of GET, POST, PUT, DELETE, HEAD, OPTIONS; default "GET"; HTTP method of the check
path	string	default "/"; Path the check requests, one of GET /reference/health-check-options
host	string	may be null; Host header of the check. Default: origin_host, else the FQDN
interval	string	default "10s"; One of the intervals of GET /reference/health-check-options
rise	integer	1–10; default 2; Passed checks in a row that bring an origin back, 1 to 10
fall	integer	1–10; default 3; Failed checks in a row that take an origin out of rotation, 1 to 10
expect	string	may be null; Expected answer, one of GET /reference/health-check-options, such as status 200 or status 2xx. Null: any 2xx or 3xx passes

Example

Point an origin to a new address with the connection limit it survives:

curl -s -X PUT -H "Authorization: Bearer $ZP_KEY" -H 'Content-Type: application/json' \
  $API/services/www.example.com/origins/origin1 \
  -d '{"name": "origin1", "address": "203.0.113.10", "port": 443, "maxconn": 200}'

Health check on a cheap endpoint:

curl -s -X PATCH -H "Authorization: Bearer $ZP_KEY" -H 'Content-Type: application/json' \
  $API/services/www.example.com \
  -d '{"backend": {"health_check": {"path": "/health", "expect": "status 200"}}}'

Behaviour

• maxconn applies per edge: set it to the concurrent connections your application survives with acceptable response times, for one edge carrying the peak. Set higher, it forwards a flood straight into the origin.
• Above maxconn the edge queues; a request waiting longer than 2 s gets 503. Beyond four times maxconn per origin (default) new requests get 503 at once, with Retry-After: 2 and X-ZP-Reason: origin-busy.
• Allowlisted sources and visitors who passed proof-of-work or earned returning-visitor credit are not cut off by that limit, see Priority.
• An origin that fails fall checks in a row leaves rotation and returns after rise successful checks. With all origins down the edge answers 503.
• origin_host and origin_sni set the Host header and SNI towards the origin when they differ from the public FQDN.
• origin_kind: static (bucket or file server) replaces the origin's 403 and 404 with the branded error pages.
• Client, server and tunnel (WebSocket) timeouts are 30 s each; support can set longer ones.
• Shield the origin: accept only the edge addresses or a private backhaul (IPsec, MPLS, CrossConnect); a direct request to the origin must fail.

In the portal: tab Origins; the Origin Connections chart shows whether maxconn is reached.