APIRequest - standardising API curl examples in Cloudflare Docs

Across the Cloudflare developer documentation, there are approximately 444 code blocks that demonstrate sending curl requests to the Cloudflare API.

Keeping these consistent and accurate is a multi-faceted problem:

• Consistency
  • Short or long flags: -X PUT vs —request PUT
  • Placeholders for parameters: {zoneID} vs {zone_id} vs $ZONE_ID vs <ZONE_ID> vs …
  • Using —data , —header “Accept: application/json” and —header “Content-Type: application/json” vs —json
  • Formatting inline JSON passed to —data or —json
• Accuracy
  • Is the URL correct?
  • Does this endpoint require an API token or an API key?
  • What token permissions does this endpoint require?
  • Is my payload correct? Am I specifying all required properties?

Consistency

Tackling consistency is difficult with a documentation site as large as ours - we have 5,716 Markdown files after all.

We have a page in our style guide that talks about our preference for long parameters, escaping quotes in the JSON body and other guidelines:

What if we could just automate all of this away with a component?

Accuracy

The majority of the information we need to ensure an example is accurate is now available in our public OpenAPI schemas.

Authentication method

If an API token, API key or both are supported is available in the security property:

paths:
  /accounts/{account_id}:
    delete:
      # ...
      security:
        - api_email: []
          api_key: []

Authorization

Permissions are available in the x-api-token-group extension for a given operation:

paths:
  /accounts/{account_id}:
    delete:
      # ...
      x-api-token-group:
        - Account Settings Write

Payload

Accepted content types and their schemas are available in the contentBody property for a given operation:

paths:
  /accounts/{account_id}:
    delete:
      # ...
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/abuse-reports_SubmitReportRequest"

Components

We know how we want our curl command to look, and we have the information available in the schemas to validate and enrich the examples, so it’s time for our components.

CURL

Our new CURL component is a simple component to take the url, method, headers, json and form properties and output a consistently formatted command:

• Long flags are used
• --json over --data and --header
• JSON strings are escaped and indented with the --json flag

As it builds on top of our code blocks, it can also highlight custom values to indicate to the user what input to change.

APIRequest

The APIRequest component wraps our new CURL component, filling in boilerplate for you such as the https://api.cloudflare.com/client/v4 base URL and validating your json input against the schema (form validation coming soon!):

• Required API token permissions are lifted from the x-api-token-group extension if present
• API tokens are preferred over API keys if possible
• json properties are validated against the schema - any missing required properties will result in an error

Conclusion

Integrating with the schema allows us to reduce duplicated work for our writers, ensure our examples are more accurate and consistent for our users and help us spot gaps when converting existing hand-written examples that rely on undocumented endpoints!

We’ve already started adopting this component in a few areas - if you want inspiration or more examples than our style guide provides, check out our component usage page: