Hyperlint OpenAPI Change Monitoring: 2024-10-15

[hyperlint-ai]

🧪 Experimental feature

Updates related to Cloudforce One Requests Management

We found 115 endpoint changes for Cloudforce One Requests Management and scanned 17 files that related to these changes. Here are the results from the scanned files:

• 17 do not require an update based on our assessment
• 0 may require an update, but we don't have enough information to say for sure
• 0 need an update based on our assessment

No files need updates according to our search relating to API changes in Cloudforce One Requests Management.

---

Updates related to Zone Cache and Settings Management

We found 30 endpoint changes for Zone Cache and Settings Management and scanned 16 files that related to these changes. Here are the results from the scanned files:

• 15 do not require an update based on our assessment
• 1 may require an update, but we don't have enough information to say for sure
• 0 need an update based on our assessment

Here are the files that may need updates. Please review the changes and make the necessary updates.

Alert for src/content/docs/cache/advanced-configuration/cache-reserve.mdx

src/content/docs/cache/advanced-configuration/cache-reserve.mdx trigged an alert, and we found changes to make. The changes are as follows:

The changes to the file are as follows:

Line 209: Consider updating the response object in this example given that the 200 response was removed.
Line 230: Consider updating the response object in this example given that the 200 response was removed.

The changes in the API were:

• /zones/{zone_id}/cache/cache_reserve changed operation GET for operation ID: zone-cache-settings-get-cache-reserve-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/cache_reserve changed operation PATCH for operation ID: zone-cache-settings-change-cache-reserve-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/cache_reserve_clear changed operation GET for operation ID: zone-cache-settings-get-cache-reserve-clear. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/cache_reserve_clear changed operation POST for operation ID: zone-cache-settings-start-cache-reserve-clear. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/origin_post_quantum_encryption changed operation GET for operation ID: zone-cache-settings-get-origin-post-quantum-encryption-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/origin_post_quantum_encryption changed operation PUT for operation ID: zone-cache-settings-change-origin-post-quantum-encryption-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/regional_tiered_cache changed operation GET for operation ID: zone-cache-settings-get-regional-tiered-cache-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/regional_tiered_cache changed operation PATCH for operation ID: zone-cache-settings-change-regional-tiered-cache-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/tiered_cache_smart_topology_enable changed operation DELETE for operation ID: smart-tiered-cache-delete-smart-tiered-cache-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/tiered_cache_smart_topology_enable changed operation GET for operation ID: smart-tiered-cache-get-smart-tiered-cache-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/tiered_cache_smart_topology_enable changed operation PATCH for operation ID: smart-tiered-cache-patch-smart-tiered-cache-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/variants changed operation DELETE for operation ID: zone-cache-settings-delete-variants-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/variants changed operation GET for operation ID: zone-cache-settings-get-variants-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/cache/variants changed operation PATCH for operation ID: zone-cache-settings-change-variants-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/settings/origin_max_http_version changed operation GET for operation ID: zone-cache-settings-get-origin-max-http-version-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

• /zones/{zone_id}/settings/origin_max_http_version changed operation PATCH for operation ID: zone-cache-settings-change-origin-max-http-version-setting. Specific change:

removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status

[bllchmbrs]

@pedrosousa , The AI identified the examples in that file but since it's not a clear cut change, this is an example of where something may require an update but needs supervision for if so.

I'm going to make some updates to the formatting but let me know your feedback!

[pedrosousa]

We're starting to get useful info! :)

My feedback:

• It would be nice if the issue said which API operations are mentioned in which MDX file(s).

• We could link to the specific code blocks in GitHub, since we already know the exact lines where those blocks start, and force code view (adding ?plain=1 to the URL).
  Based on one of the impacted code blocks pointed out in the GitHub issue, the link to line 209 using code view would be https://github.com/cloudflare/cloudflare-docs/blob/40339359e9f359258905b94fe9190ce41e66128b/src/content/docs/cache/advanced-configuration/cache-reserve.mdx?plain=1#L209

• The summary doesn't seem to exactly match the change details:

  Line 209: Consider updating the response object in this example given that the 200 response was removed.
  

  The 200 response was not removed, just the result element from one of the sub-objects:

  removed the required property '/allOf[#/components/schemas/cache_zone_cache_settings_response_single]/allOf[#/components/schemas/cache_api-response-single]/allOf[#/components/schemas/cache_api-response-common]/result' from the response with the '200' status
  

Btw, I checked the response we have in Dev Docs vs. the example in the API reference website and it seems that there were no relevant changes — probably just the way the response is being described in the schema.

[crwaters16]

@bllchmbrs Pedro is still running this show, but I just wanted to comment that this is SO HELPFUL!

[bllchmbrs]

@crwaters16 - thank you! Although we're just getting started, this is all about to be supercharged :)

Onto your feedback @pedrosousa ...

It would be nice if the issue said which API operations are mentioned in which MDX file(s).

I'm not sure I 100% understand. I'll log this for discussion next week to make sure we're on the same page. I'll look deeper into this to see if I can tweak the report to get more aligned with your thoughts.

We could link to the specific code blocks in GitHub......

Absolutely, I had this in mind too. Should be done for today's report.

The summary doesn't seem to exactly match the change details....

Answer 1: Nuanced answer
You'll notice the text says "removed the required property". In my understanding, the engineering team changed the API such that the 200 response does not require the mentioned property in the response, not that it was removed entirely. The AI didn't get the full nuance behind that 'sub-object' change from required => optional, so it was 'unsure' in its suggestion, e.g., "consider updating".

probably just the way the response is being described in the schema.
I agree with your final assessment!

Answer 2: so, what's next?

This is the tuning process we're going to go through as we customize it to your OpenAPI/Wrangler + Docs. I've got ideas on how to improve this / the recommendations / the changes.

We'll continue airing on the side of caution and surface these potential issues to get your feedback. We can always tone it down in next week's check-in.

[pedrosousa]

It would be nice if the issue said which API operations are mentioned in which MDX file(s).

I'm not sure I 100% understand. I'll log this for discussion next week to make sure we're on the same page. I'll look deeper into this to see if I can tweak the report to get more aligned with your thoughts.

Let me try to clarify. Based on the issue text:

Here are the files that may need updates. Please review the changes and make the necessary updates.

Alert for src/content/docs/cache/advanced-configuration/cache-reserve.mdx
[src/content/docs/cache/advanced-configuration/cache-reserve.mdx](https://github.com/cloudflare/cloudflare-docs/blob/40339359e9f359258905b94fe9190ce41e66128b/src/content/docs/cache/advanced-configuration/cache-reserve.mdx) trigged an alert, and we found changes to make. The changes are as follows:

The changes to the file are as follows:

Line 209: Consider updating the response object in this example given that the 200 response was removed.
Line 230: Consider updating the response object in this example given that the 200 response was removed.

I couldn't determine that cache-reserve.mdx contained references to the GET /zones/{zone_id}/cache/cache_reserve and POST /zones/{zone_id}/cache/cache_reserve_clear API operations. I had to open the linked MDX file, check the code blocks pointed out by hyperlint, and take note of the endpoint mentioned above those code blocks. Then, I checked the API reference site, searched for those API operations (with changes), and compared the (updated) 200 responses with the corresponding code block in Dev Docs to find any relevant changes.

Whatever helps us quickly get to the right API operation in the API reference site, either by providing us with the operation name ("Get Cache Reserve setting") or the endpoint (/zones/{zone_id}/cache/cache_reserve), will help with this validation process.

[bllchmbrs]

@pedrosousa , I think we can close this particular issue out.

However, during testing, I may have found an example that appears accurate.

The change is:

• /accounts/{account_id}/intel/miscategorization changed operation POST for operation ID: miscategorization-create-miscategorization. Specific change:

the request property 'ip' became not nullable

The alert is:

🚨 change-categorization.mdx triggered an alert and we found changes to propose.

The changes to the file are as follows:
Line 77: Update the example to reflect that the 'ip' property is not nullable by providing a valid IP address.

Is there any way that you or someone else can double check whether this is accurate?

If so, I can update the system to perform more reliably in these situations.

[pedrosousa]

I'm not sure what happened, but both the live API reference site and the public API schema file I checked still say that ip is nullable. Can you confirm if this change is still being detected?

[bllchmbrs]

@pedrosousa , I've got a strong hypothesis. Since the OpenAPI spec is auto-built from some source, my estimate would be that for a moment, it was 'nullable' but that the team continued making changes and it stopped.

It's not still detected (as it would have shown up in the most recent report). That's my standing hypothesis. This is all helpful (if a little annoying - thanks for your patience!)