Cloudflare publishes OpenAPI schemas for its API

Cloudflare has made its API definitions publicly available as OpenAPI schemas via GitHub. The schemas, which will be updated regularly as the company adds and modifies endpoints, are machine-readable definitions that can plug into the wider ecosystem of OpenAPI tooling.

The move is a shift away from the JSON Hyper-Schema standard Cloudflare previously used to define roughly 600 API endpoints. While both formats carry similar structural information — method types, descriptions, and request/response definitions — the OpenAPI ecosystem is considerably richer. That wider tooling support is the primary motivation for the transition, both internally and for customers.

What OpenAPI definitions enable

Most users won't interact with the schemas directly. The first consumer of the new format is Cloudflare's own API documentation, which now relies on the open source Stoplight Elements to generate its pages. That replaced a custom-built documentation site that was difficult to maintain. The schemas also make it easier for Cloudflare engineers to author new API definitions, since OpenAPI is already familiar to many developers.

For customers who want to use the schemas themselves, two practical applications stand out.

Mocking the API for tests

Developers who want to test code that calls the Cloudflare API without making live requests can use the schemas to run a local mock server. Tools like Stoplight Prism read the OpenAPI definitions and simulate API behavior, including edge cases such as rate limiting or 500 errors. That allows unit and integration tests to validate that code adheres to the API contract without the overhead of managing real resources in CI/CD pipelines.

$ docker run --init --rm \
  -v /home/user/git/api-schemas/openapi.yaml:/tmp/openapi.yaml \
  -p 4010:4010 stoplight/prism:4 \
  mock -h 0.0.0.0 /tmp/openapi.yaml

Requests can then be sent to the mock server to check for API contract violations locally:

$ curl -sX PUT localhost:4010/zones/f00/activation_check \
  -Hx-auth-email:[email protected] -Hx-auth-key:foobarbaz | jq
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  }
}

Generating client libraries

Cloudflare maintains official libraries for some languages, but not all of them. With the OpenAPI schemas, developers can use tools like openapi-generator to produce a client library in a wide range of programming languages. For example, a Java client can be generated with:

git clone https://github.com/openapitools/openapi-generator
cd openapi-generator
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
   -i https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml \
   -g java \
   -o /var/tmp/java_api_client

The generated client can then be used in application code to communicate with Cloudflare's API.

How the transition happened

Migrating hundreds of endpoint definitions from JSON Hyper-Schema to OpenAPI by hand was not practical, especially since teams were continuously adding endpoints. Cloudflare instead built a conversion tool that auto-generated OpenAPI schemas from the existing JSON Hyper-Schema definitions. The tool was refined iteratively by running OpenAPI validation software over its output to catch remaining issues.

During the transition period, both schema formats had to stay in sync because the old API docs only understood JSON Hyper-Schema. Updates made to the existing schemas by engineering teams — including textual changes from Cloudflare's product content team — were automatically carried into the new OpenAPI output through the converter. That removed the need to slow down API development while the migration was in progress.

The switch was completed when the new API documentation launched, since the old docs were the main remaining consumer of the JSON Hyper-Schema format. At that point the old schema format was retired and OpenAPI became the source of truth.

Next steps

With the OpenAPI foundations in place, Cloudflare plans to explore tooling that can reduce the effort required to define new APIs internally, including automatically generating schemas from code annotations. Externally, the schemas open up the possibility of generating and supporting more client libraries across a broader set of programming languages. Cloudflare is also interested in what customers build using the schemas directly.