Skip to content

Commit 17fc4e3

Browse files
korinnekorinne
committed
updates title
1 parent ccd5040 commit 17fc4e3

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

‎src/content/changelog/workers/2025-09-03-new-workers-api.mdx

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: Introducing the new Workers API. From eight confusing endpoints to three clear resources
3+
description: Simpler Workers API, SDK methods, and Terraform resources for directly managing Workers, Versions, and Deployments
4+
date: 2025-09-03
5+
---
6+
You can now manage [**Workers**](/api/resources/workers/subresources/beta/subresources/workers/methods/create/), [**Versions**](/api/resources/workers/subresources/beta/subresources/workers/models/worker/#(schema)), and [**Deployments**](/api/resources/workers/subresources/scripts/subresources/content/methods/update/) as separate resources with a new, resource-oriented API (Beta).
7+
8+
This new API is supported in our [Terraform provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs) and the [Cloudflare Typescript SDK](https://github.com/cloudflare/cloudflare-typescript), allowing platform teams to manage a Worker's infrastructure in Terraform, while development teams handle code deployments from a separate repository or workflow. We also designed this API with agents in mind, as a clear, predictable structure is essential for them to reliably build, test, and deploy applications.
9+
10+
### Try it out
11+
- [**New beta API endpoints**](/api/resources/workers/subresources/beta/)
12+
- [**Cloudflare TypeScript SDK v4.6.0**](https://github.com/cloudflare/cloudflare-typescript)
13+
- [**Terraform provider v5.9.0**](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs): [`cloudflare_worker`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/worker) , [`cloudflare_worker_version`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/worker_version), and [`cloudflare_workers_deployments`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/workers_deployment) resources.
14+
- See full examples in our [Infrastructure as Code (IaC) guide](/workers/platform/infrastructure-as-code)
15+
16+
17+
![**Before and after**](~/assets/images/workers/platform/endpoints.png)
18+
19+
## Before: Eight endpoints with mixed responsibilities
20+
The existing API was originally designed for simple, one-shot script uploads.
21+
22+
```sh
23+
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/scripts/$SCRIPT_NAME" \
24+
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
25+
-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
26+
-H "Content-Type: multipart/form-data" \
27+
-F 'metadata={
28+
"main_module": "worker.js",
29+
"compatibility_date": "$today$"
30+
}' \
31+
-F "[email protected];type=application/javascript+module"
32+
33+
```
34+
35+
This structure works great for conveniently creating a Worker, uploading all of its code, and deploying it immediately -- but came with its own problems, such as:
36+
37+
- **A Worker couldn't exist without code**: To create a Worker, you had to upload its code in the same operation. While this doesn't pose a problem for smaller teams, this prevented platform teams in larger organizations from provisioning Workers with the proper settings, and then handing them off to development teams to deploy the actual code.
38+
39+
- **Updating settings was confusing and fragmented**: With the existing API, configuration is scattered across eight different endpoints with overlapping responsibilities. This made it challenging for human developers (and even more difficult for automated agents) to reliably update a Worker's settings. You had to guess between [`/settings`](/api/resources/workers/subresources/scripts/subresources/schedules/methods/update/) and [`/script-settings`](/api/resources/workers/subresources/scripts/subresources/settings/methods/edit/), with not a lot of clarity about which endpoint updated all versions or a specific version of a Worker.
40+
41+
- **Scripts used names as primary identifiers**: The existing API uses the Worker script name as the primary identifier for a Worker, which meant that if you wanted to rename a Worker via API, you needed to deploy an entirely new script and update every reference across your infrastructure. If you were using Terraform, renaming a Worker could easily result in destroying the Worker altogether.
42+
43+
## After: Three resources with clear boundaries
44+
We have consolidated the API around three core resources with distinct boundaries: [**Worker**](/api/resources/workers/subresources/beta/subresources/workers/methods/create/), [**Versions**](/api/resources/workers/subresources/beta/subresources/workers/models/worker/#(schema)), and [**Deployment**](/api/resources/workers/subresources/scripts/subresources/content/methods/update/). All endpoints now use clean JSON payloads, with script content embedded as `base64`-encoded string, a simpler and more reliable approach than the previous `multipart/form-data` format.
45+
- **Worker**: The parent resource representing your application. It has a stable UUID and holds persistent settings like `name`, `tags`, and `logpush`. You can now create a Worker to establish its identity and settings **before** any code is uploaded.
46+
47+
- **Version**: An immutable snapshot of your code and its specific configuration, like bindings and `compatibility_date`. Creating a new version is a safe action that doesn't affect live traffic.
48+
49+
- **Deployment**: An explicit action that directs traffic to a specific version.
50+
51+
## Why this matters
52+
53+
### Separation of concerns
54+
55+
The new API enables proper separation of concerns between infrastructure and application teams.
56+
57+
#### Example: Typescript SDK
58+
```ts
59+
// Step 1: Platform team creates the Worker resource (no code needed)
60+
const worker = await client.workers.beta.workers.create({
61+
"payment-service",
62+
account_id: "...",
63+
observability: {
64+
enabled: true,
65+
},
66+
});
67+
68+
// Step 2: Development team adds code and creates a version later
69+
const version = await client.workers.beta.workers.versions.create(worker.id, {
70+
account_id: "...",
71+
main_module: "payment-service-script",
72+
compatibility_date: "$today",
73+
bindings: [ /*...*/ ],
74+
modules: [
75+
{
76+
name: "payment-service",
77+
content_type: "application/javascript+module",
78+
content_base64: Buffer.from(scriptContent).toString("base64"),
79+
},
80+
],
81+
});
82+
83+
// Step 3: Deploy explicitly when ready
84+
const deployment = await client.workers.scripts.deployments.create(worker.name, {
85+
account_id: "...",
86+
strategy: "percentage",
87+
versions: [
88+
{
89+
percentage: 100,
90+
version_id: version.id,
91+
},
92+
],
93+
});
94+
````
95+
#### Example: Terraform
96+
For those using Terraform, you can now track the Worker's existence without needing to also manage its configuration and deployments. This gives you flexibility to use Wrangler for building and deploying your code, while still using Terraform as your source of truth for your Worker's infrastructure.
97+
98+
```tf
99+
resource "cloudflare_worker" "my_worker" {
100+
account_id = "..."
101+
name = "my-important-service"
102+
}
103+
# Manage Versions and Deployments here or outside of Terraform
104+
# resource "cloudflare_worker_version" "my_worker_version" {}
105+
# resource "cloudflare_workers_deployment" "my_worker_deployment" {}
106+
```
107+
108+
### Predictable settings
109+
Configuration now has an obvious home. Worker settings persist across all versions of the Worker, and Version settings are specific to a code snapshot.
110+
111+
```sh
112+
# Worker settings (the parent resource)
113+
PUT /workers/workers/{id}
114+
{
115+
"name": "payment-service",
116+
"tags": ["production"],
117+
"logpush": true,
118+
}
119+
```
120+
121+
```sh
122+
# Version settings (the "code")
123+
POST /workers/workers/{id}/versions
124+
{
125+
"compatibility_date": "$today",
126+
"bindings": [...],
127+
"modules": [...]
128+
}
129+
```
130+
131+
### Dual addressing for stability and convenience
132+
133+
The `/workers/workers/` path now supports addressing a Worker by both its immutable UUID and its mutable name.
134+
135+
```sh
136+
# Both work for the same Worker
137+
GET /workers/workers/29494978e03748669e8effb243cf2515 # UUID (stable for automation)
138+
GET /workers/workers/payment-service # Name (convenient for humans)
139+
```
140+
This dual approach means:
141+
- Developers can use readable names for debugging.
142+
- Automation can rely on stable UUIDs to prevent errors.
143+
- Terraform can rename Workers without destroying and recreating them.
144+
145+
146+
## Learn more
147+
- [Infrastructure as Code (IaC) guide](/workers/platform/infrastructure-as-code)
148+
- [API documentation](/api/resources/workers/subresources/beta/)
149+
- [Versions and Deployments overview](/workers/configuration/versions-and-deployments/)
150+
151+
## Technical notes
152+
153+
- Current APIs remain operational during beta, and any deprecation notice will come with a defined support period.
154+
- Legacy Terraform resources and SDK methods will be supported until the next major version.

0 commit comments

Comments
 (0)