Skip to main content
Most APIs on jojapi front a server you already run. The template describes where the edge gateway forwards a consumer’s request and which headers and parameters it adds; the platform generates your API’s Worker from it. Consumers only ever see https://your-api.jojapi.net.
Every API runs on the edge gateway as its own Worker, and the Worker tab shows the template described here. A new API starts with an empty template: until you save its origin, requests to it answer 424 No available API targets and are not billed. The My APIs list shows what each API’s Worker runs: Template (generated from the template) or Code (your own Worker code).
Open your API in Studio → Worker. Every save of the template regenerates your API’s Worker as a preview within seconds; the confirmation tells you whether it built. Test it, then Deploy to production from the bar on the Worker tab. The first save of a new API’s template goes to production at once, since nothing runs there yet.

The template

Origins: one or more base URLs including any path prefix, e.g. https://api.example.com/v2. The consumer’s path and query string are appended as they are: /users/42?x=1 reaches https://api.example.com/v2/users/42?x=1. With several origins a request goes to one of them at random and moves on to the next when the first does not answer (network error or timeout), which gives you simple load balancing and failover. IP addresses and non-standard ports work too; such requests leave through the platform’s egress relay. A variable may stand in for the host: https://{env.HOST}.
Requests from the gateway do not come from fixed IP addresses. To let only JoJ API reach your origin, send a secret header from the template and check it on your server; see Recognize requests with a secret header.
HTTP method: the consumer’s method, or an override. Timeout: up to 90 seconds per origin (the platform’s maximum). Request headers and query parameters: add or overwrite values (a header can also be removed from the forwarded request). Values accept placeholders. Switches:
  • Forward the consumer’s headers — off means only the headers you set reach the origin.
  • Forward the consumer’s query string — off means only the parameters you set are sent.
  • Consumer context headers — sends x-jojapi-user-id, x-jojapi-user-nick, x-jojapi-user-plan and x-jojapi-endpoint-credits to the origin.
Proxy: a secret variable holding your proxy URL (HTTP, HTTPS or SOCKS5, credentials included); requests then leave through the egress relay via your proxy.

Beyond the template

Different origins or paths per endpoint, response rewrites, request body transformations, several upstream calls per request, or usage computed from the response body are matters of code. View generated code shows the Worker the template produces; Edit code takes it over. APIs that had endpoint-specific targets on the classic gateway were moved in code mode, with generated code that behaves exactly like those targets did. See Worker code.

Placeholders

Header values and query parameters interpolate {placeholder} values from the request and the consumer’s account: The Vars button on each field lists them, including your variables.

Variables

Variables are named values bound to your API’s Worker. Use them for anything you would rather not type into the template: upstream API keys, tokens, a proxy URL.
  • Secret variables are encrypted at rest and never shown again after you save them. To rotate one, save a new value under the same name.
  • Plain variables are shown in Studio; use them for non-sensitive settings such as a region or a version.
Reference a variable as {env.NAME} in the template, or read env.NAME in code. Names use capital letters, digits and underscores, for example UPSTREAM_API_KEY. A variable the template uses cannot be deleted: remove it from the template first, and deploy that change if production still runs a template that uses it.
Static header values that looked like credentials were moved into secret variables automatically when your API was moved to the edge gateway.

Recognize requests with a secret header

Requests from the gateway do not come from fixed IP addresses (most leave from Cloudflare’s network, which every Cloudflare customer shares), so filtering by IP address cannot tell JoJ API apart. Have the template send a header that only JoJ API knows, and let your server accept only requests that carry it:
  1. Save a long random value (32 characters or more) as a secret variable such as ORIGIN_SECRET.
  2. Add a request header to the template, for example X-Origin-Secret, set to {env.ORIGIN_SECRET}.
  3. Make your server reject requests without that header and value:
    In application code, compare the value with a constant-time comparison.
  4. Check that your API still answers through the gateway.
To rotate the secret without downtime, accept both the old and the new value on your server, save the new value in Studio, then drop the old one.

Billing

What each request costs is configured per endpoint in Billable objects. Metered amounts come from structured usage sources (a response header, a header key, a JSON field) that the gateway reads from the origin’s response, so a template API needs no code to bill by usage.