Cloudflare Docs
API Shield
Edit this page
Give us feedback
Set theme to dark (⇧+D)

API Routing

API Shield Routing enables customers to create a unified external-facing API that routes requests to different back-end services that may have different paths and hosts than the existing zone and DNS configuration.

​​ Process

You must add Source Endpoints to Endpoint Management through established methods, by uploading a schema, via API Discovery, or by adding manually, before creating a Route.

To create a Route, you will need the operation ID of the Source Endpoint. To find the operation ID in the dashboard:

  1. Log in to the Cloudflare dashboard and select your account and domain.
  2. Select Security > API Shield.
  3. Filter the endpoints to find your Source Endpoint.
  4. Expand the row for your Source Endpoint and note the operation ID field.
  5. Select the copy icon to copy the operation ID to your clipboard.

Once your Source Endpoints are added to Endpoint Management, use the following API calls to create and verify routes on any given operation ID:

​​ Create a Route

cURL command
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/operations/{operationID}/route" \
--header "Content-Type: application/json" \
--data '{"route": "https://api.example.com/api/service"}'
Response
{
"result": {
"route": "https://api.example.com/api/service"
},
"success": true,
"errors": [],
"messages": []
}

You can reorder path variables if they are present. For example, you can route /api/{var1}/users/{var2} to /{var2}/users/{var1}. Segments of the path that are not variables may be added or omitted entirely.

​​ Verify a Route

cURL command
curl --request GET "https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/operations/{operationID}/route" \
--header "Content-Type: application/json"
Response
{
"result": {
"route": "https://api.example.com/api/service"
},
"success": true,
"errors": [],
"messages": []
}

​​ Remove a Route

cURL command
curl --request DELETE "https://api.cloudflare.com/client/v4/zones/{zoneID}/api_gateway/operations/{operationID}/route" \
--header "Content-Type: application/json"
Response
{
"result":{},
"success":true,
"errors":[],
"messages":[]
}

​​ Test a Route

After sending a request to your Source Endpoint, you should see the contents of the back-end service as if you called the Target Endpoint directly.

If API Shield returns unexpected results, check your Source Endpoint host, method, and path and verify the Route to ensure the Target Endpoint value is correct.

​​ Availability

API Shield Routing is currently in an open beta and is only available for Enterprise customers subscribed to API Shield. Enterprise customers who have not purchased API Shield can preview API Shield as a non-contract service in the Cloudflare dashboard or by contacting your account team.

​​ Limitations

The Target Endpoint cannot be routed to a Worker if the Route is to the same zone.

You cannot change the method of a request. For example, a GET Source Endpoint will always send a GET request to the Target Endpoint.

You must use all of the variables in the Target Endpoint that appear in the Source Endpoint. For example, routing /api/{var1}/users/{var2} to /api/users/{var2} is not allowed and will result in an error since {var1} is present in the Source Endpoint but not in the Target Endpoint.