API spec compliance to OpenAPI standard

Hi

I have been using the cloudflare API for some time now and I have a question which is bothering me: why is the API specs (either on GitHub - cloudflare/api-schemas or Cloudflare API Documentation) not conform to the OpenAPI specs ?

Couple of examples:

  • the openAPI spec is defining that response code for API calls should fit β€˜[1](?:[0-9]{2}|XX)$’ while the the Cloudflare API specs defines return code as 4xx (lower case)
  • default values set as strings while they are of a different type (for example in workers-kv_query the default is set to β€œβ€ which would define a string and not an array)
  • default values and type/enum fiels not matching(for example in /radar/attacks/layer3/timeseries metric value should be BYTES or BYTES_OLD but is defaulted to bytes)
  • …

(my examples are based on the output of the openapi-spec-validator so there is a bias and might be coming from the validation tool itself in terms of interpretation)

Obviously, this does not prevent the API to be usable but it would be β€œnice” if the spec file would be comform to the standard.

tx


  1. 1-5 β†©οΈŽ

I would recommend dropping feedback at New API Site Feedback for the API docs.

Unfortunately I wouldn’t be too optimistic about a resolution though - I and many others have been raising issues around the API docs >12 months now, and very few of them have been resolved.

1 Like

Thanks.
Will try the feedback form but I indeed have little hopes on the topic.
As a practical joke, I am tempted to inject Cloudflare own spec into their API fw Gateway product …