Today we’re announcing the sunsetting of CloudFlare’s first client API, API v1. Starting November 9th, 2016 at noon Pacific Time (20:00 UTC), CloudFlare will no longer be supporting API v1.
While it is bittersweet to let our first API from CloudFlare’s early days go, we are so excited to show you all of the great things about our latest API: API v4. We’re confident that once you get started using it, you’ll see how easy API v4 makes managing your CloudFlare settings.
(For those of you who are curious where CloudFlare’s API v2 and v3 went, they ran away with IPv5 and PHP 6.)
If you are using API v1 and need to migrate to API v4, we’ve written extensive migration docs here for you to follow. They contain every API call from v1 and their equivalent in v4 side by side.
What will happen after the sunset?
After CloudFlare discontinues support for API v1 in November 2016, any calls to API v1 will return the HTTP status code 410 Gone with the message: “This API has been deprecated in favor of API v4, available at https://api.cloudflare.com.”
What can you do with API v4?
CloudFlare uses the v4 API to power our customer dashboard, so unlike API v1, it has support for every single feature on CloudFlare. The list of features API v4 has that weren’t previously available in v1 is extensive. Here's a list:
- Manage your zone's Page Rules.
- Upload a new SSL certificate for a zone.
- Manage Origin Certificates for your zones.
- Manage your Railgun connections.
- Manage custom error pages for your zone.
- View analytics by status code and by data center (Enterprise only).
- Set firewall access rules at a user level, allowing access rules to be set across all zones you control.
- Added options for access rules including:
- IPv6 support
- IPv4 and IPv6 CIDR support
- ASN support
- Country support
- Additional CAPTCHA and JavaScript Challenge options
- Pass through 502 and 504 error pages from your origin server instead of showing a CloudFlare error page (Enterprise only).
- Create mobile redirects.
- Toggle on/off response buffering vs. streaming (Enterprise only).
- Turn on Query String Sorting in cache (Enterprise only).
- Manage Polish.
- Manage HSTS.
- Change your TLS Client Auth setting.
- Add/remove the True-Client-IP header (Enterprise only).
- Force traffic to connect over TLS 1.2 only.
- Purge by Tag (Enterprise only).
- Add zones to your account or initiate another zone activation check.
- Manage your user account.
- View your billing profile or billing history
- View subscriptions on an app and zone level.
Besides this extensive list, API v4 has support for Multi-User for Enterprise customers and for Virtual DNS management for Virtual DNS customers.
JSON in, JSON out
As well as the added functionality, developers will like working with the v4 API because of the consistent use of JSON in both the request and response - no need to parse and transcode data in and out of JSON and form-encoded data.
While API v1 used form-encoded data in the request and JSON in the response, API v4 uses JSON throughout. This reduces any extra work on the client or server-side to translate the data between request and response.
A namespace for humans
You’ll also find the namespacing in API v4 more friendly to interact with. For example, the Always Online setting previously looked like this:
"ob": 1
While v4 represents Always Online as:
{
"id": "always_online",
"value": "on",
"editable": true,
"modified_on": "2014-01-01T05:20:00.12345Z"
}
How can you get started using API v4?
We have plenty of resources for you to get started with. If you need to migrate from using API v1 to using API v4, we have thorough migration docs for you written here. If you want to jump right in, you can find the API v4 documentation here. And if you’re a Go, Python or Node.js user, we have client libraries you can use to interact with the API available on our github here: (Go client, Python client and Node.js client).