APIShield

Cloudflare’s API Shield protects your API endpoints by validating incoming requests against an OpenAPI v3 schema. It can monitor, log, or block requests that don’t match your schema definition, helping prevent malformed requests and potential security issues.

Schema Validation

Construct an APIShield from an OpenAPI v3 schema. The schema can be provided as a string, a file path, a URL, or a typed OpenAPI object.

For example, given the following schema.yaml file:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users:
    get:
      operationId: getUsers
      responses:
        '200':
          description: Success
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User details

You can construct and configure an APIShield for your Cloudflare Zone with the following code:

import { APIShield, Zone } from "alchemy/cloudflare";

const zone = await Zone("example.com");

const apiShield = await APIShield("api-validation", {
  zone,
  // or by domain name:
  // zone: "example.com",
  schema: "./schema.yaml",
});

From a File

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "./schema.yaml",
});

From a URL

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "https://api.example.com/openapi.yaml",
  // or:
  // schema: new URL("https://api.example.com/openapi.yaml"),
});

From a YAML String

const apiShield = await APIShield("api-validation", {
  zone,
  schema: `
    openapi: 3.0.0
    info:
      title: My API
      version: 1.0.0
    paths:
      # ... etc.
  `,
});

From a JSON String

const apiShield = await APIShield("api-validation", {
  zone,
  schema: `
    {
      "openapi": "3.0.0",
      "info": {
        "title": "My API",
        "version": "1.0.0"
      },
      "paths": {
        // ... etc.
      }
    }
  `,
});

From an Object

const apiShield = await APIShield("api-validation", {
  zone,
  schema: {
    openapi: "3.0.0",
    info: {
      title: "My API",
      version: "1.0.0",
    },
    paths: {
      "/users": {
        get: {
          operationId: "getUsers",
        },
      },
    },
  },
});

Mitigation Actions

API Shield supports three mitigation actions:

none: Monitor and analyze API traffic without impact
log: Track non-compliant requests for analysis
block: Actively protect endpoints by blocking invalid requests

Default Mitigation

Each API Endpoint in the schema (path + HTTP method) will be configured with a default mitigation action of "none", but you can override this with the defaultMitigation option.

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "./schema.yaml",
  defaultMitigation: "log" // Log violations (requires paid plan)
});

Unknown Operation Mitigation

Use the unknownOperationMitigation option to configure the action for requests that don’t match any operation in the schema:

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "./schema.yaml",
  unknownOperationMitigation: "log" // Log requests to undefined endpoints
});

Endpoint Mitigations

Use the mitigations option to configure different actions for specific endpoints and methods:

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "./schema.yaml",
  mitigations: {
    // apply to all methods on the /users path
    "/users": "log",
    "/users/{id}": {
      // block invalid POST requests to /users/{id}
      post: "block",
      // log invalid GET requests to /users/{id}
      get: "log"
    }
  }
});

Disable Validation

Use the enabled option to disable validation for the APIShield:

const apiShield = await APIShield("api-validation", {
  zone,
  schema: "./schema.yaml",
  enabled: false, // Disable validation
});