REST API reference for SaaS

[mnocon]

We have to redo the REST API reference for SaaS:

1. It's based on Experience, not Commerce
2. Badges (Experience, Commerce, LTS Update) make no sense here
3. Download links should point at the "saas" branch
4. Removing the Corporate Account, URLWIldcards, and JWT Token endpoints - it would be better to generate that on the SaaS instance itself, something to improve in the future

The build itself is done in #3430

Preview: https://ez-systems-developer-documentation--3430.com.readthedocs.build/en/3430/api/rest_api/rest_api_reference/rest_api_reference.html
Diff: https://diffshub.com/ibexa/documentation-developer/pull/3430

[github-actions]

Preview of modified files: no change to preview.

[github-actions]

Summary

Status	Count
🔍 Total	71533
🔗 Unique	2685
✅ Successful	1142
⏳ Timeouts	0
🔀 Redirected	9
👻 Excluded	70381
❓ Unknown	0
🚫 Errors	10
⛔ Unsupported	0

Errors per input

Errors in site/ibexa_products/cohesivo_saas_guide/index.html

• [ERROR] file:///home/runner/work/documentation-developer/documentation-developer/repositories/userdoc-saas/site/content_management/translate_content/index.html#manage-translation-services-and-language-pairs (at 4977:41) | Cannot find fragment
• [301] https://www.ibexa.co/about-ibexa/contact-us (at 4943:51) | Rejected status code: 301 Moved Permanently
• [301] https://www.ibexa.co/products/ibexa-cloud (at 5010:108) | Rejected status code: 301 Moved Permanently
• [301] https://www.ibexa.co/products/pricing (at 4947:36) | Rejected status code: 301 Moved Permanently
• [301] https://www.raptorservices.com/ (at 4983:146) | Error (cached)
• [301] https://www.raptorservices.com/ (at 4983:67) | Error (cached)

Errors in site/infrastructure_and_maintenance/security/reporting_issues/index.html

• [301] https://www.ibexa.co/software-information/security (at 4630:69) | Rejected status code: 301 Moved Permanently

Errors in site/multisite/translations_management/configure_translations_management/index.html

• [ERROR] file:///home/runner/work/documentation-developer/documentation-developer/repositories/userdoc-saas/site/content_management/translate_content/index.html#manage-translation-services-and-language-pairs (at 4636:17) | Cannot find fragment

Errors in site/recommendations/raptor_integration/raptor_connector/index.html

• [301] https://www.raptorservices.com/ (at 4518:17) | Rejected status code: 301 Moved Permanently

Errors in site/recommendations/raptor_integration/raptor_connector_guide/index.html

• [301] https://www.raptorservices.com/ (at 4757:22) | Rejected status code: 301 Moved Permanently

Redirects per input

Redirects in site/ibexa_products/cohesivo_saas_guide/index.html

• https://www.ibexa.co/about-ibexa/contact-us --[301]--> https://ibexa.ai/about-ibexa/contact-us
• https://www.ibexa.co/products/ibexa-cloud --[301]--> https://ibexa.ai/products/ibexa-cloud
• https://www.ibexa.co/products/pricing --[301]--> https://ibexa.ai/products/pricing

Redirects in site/infrastructure_and_maintenance/security/reporting_issues/index.html

• https://www.ibexa.co/software-information/security --[301]--> https://ibexa.ai/software-information/security

Redirects in site/product_catalog/quable/quable/index.html

• https://www.quable.com/en --[301]--> https://quable.com/en

Redirects in site/product_catalog/quable/quable_guide/index.html

• https://www.quable.com/en --[301]--> https://quable.com/en

Redirects in site/recommendations/raptor_integration/raptor_connector/index.html

• https://www.raptorservices.com/ --[301]--> https://raptorservices.com/

Redirects in site/recommendations/raptor_integration/raptor_connector_guide/index.html

• https://www.raptorservices.com/ --[301]--> https://raptorservices.com/

Full Github Actions output

[mnocon]

About this, Claude says the following:

Both are needed only because of filter-out. Neither is doing anything for the endpoints you keep. I measured this on the saas spec (202 paths, 546 schemas, 42 tags).

saas/remove-unused-tags: needed.
- On the original spec it removes nothing, because all 42 tags have endpoints.
- After filter-out, exactly three tags are left with no endpoints: Url Wildcard, User Token and Corporate Account.
- filter-out only removes the endpoints, not the tag definitions. I checked earlier that without this decorator Redoc still shows the three as empty groups in the sidebar.

remove-unused-components: not needed for the HTML, only for the YAML and JSON downloads.
- Redoc renders only the schemas that endpoints reference. The config and template have no schema-definitions section, so leftover schemas never show on the page.
- Without it, the downloadable specs keep the 32 schemas that only the removed endpoints used, such as Company, Member, the URL wildcard schemas and the JWT token schemas. Anyone reading the files would still see Corporate Account and the other removed features.
- It also drops 11 schemas that were already unused before filtering: CartProduct, CartQuery, ContentCreateContentType, ContentMetadataUpdate, Country, CountryList, CountryListWrapper, LanguageCode, ProductContentUpdate, UserGroupUnassign, VersionTranslationInfo. Nothing references them, so removing them changes nothing visible. The two Cart ones are left over from Commerce, and the Experience build may not contain them anyway.

I'd keep both. If you're fine with the downloads still containing schemas for the removed groups, you can drop remove-unused-components. If you ever drop filter-out, both become unnecessary.

[adriendupuis]

I would remove this file, almost everything as been resorted in-code now
see #3194