[docs] Missing valid PageRuleAction values from documentation

[OJFord]

I suppose because this library just passes them straight through without validation, and because the documentation is generated, valid values for PageRuleAction.Value (depending on PageRuleAction.ID are not given.

The majority of them can be easily guessed from the web UI, but not all of them, and some of them would be guessed incorrectly; for example:

• TTLs can be given as any int (this might be guessed, but from the web UI you might think only the dropdown values are acceptable)
• SSL > Full Strict is just "strict"
• Cache levels are way different! 'No Query String' is "basic", 'Ignore Query String' is `"simplified", etc.

It's discoverable, but docs would be helpful. (I just set them no the web UI, then curled to see what it should be.)

I suppose they wouldn't even need to be on cloudflare-go docs if the options were fully enumerated on the main API docs - which, as far as I can tell, they're not.

[jamesog]

I'll discuss this with some people internally and see how we want to handle this. We could update the comments in the code here but it would keep getting out of sync with the API.

I'll try and find out if it's possible for the api.cloudflare.com docs to have an exhaustive list of actions and values.

[handrews]

@OJFord @jamesog I'm not sure when (if ever) this will help with v4, but as we move towards the next generation of APIs we plan to publish the JSON Schemas used to generated the documentation so that clients can be driven from the same descriptions of the API. This will ensure that clients and the API docs are always in sync going forward, and the the schemas correctly validate all JSON representations.

We may or may not be able to retrofit this for v4- some of the v4 design decisions are not conducive to easily supporting a fully schema-driven approach. We also want to get feedback on the idea on a few new APIs before going all-in on it across the board.

Look for some blog posts that I'll be publishing in the coming few weeks with more details.

In the meantime, I don't know the specifics of these exact fields but assuming nothing unusual is going on, we should definitely enumerate sets of values correctly in the docs.

[jamesog]

Thanks @handrews! I'll raise another internal ticket to track this.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.