Add UPS API Best Practices section

[smrithijayarajan]

Summary

This PR adds a comprehensive "UPS API Best Practices" section to the User Provisioning Service v4 documentation.

Changes Made

• New Section: Added "UPS API Best Practices" after the "Access Token Usage" section
• Location: Inserted at line 58 in v4.user-provisioning.md
• Content: 234 lines of best practices guidance

What's Included

Key Recommendations

• When to use /Bulk/ endpoint vs /Users/ endpoint
• Best practices for PATCH vs PUT operations
• Provision completion tracking (polling with exponential backoff vs webhook notifications)
• Pre-validation strategies to reduce failure rates
• Handling long-pending provision requests (240-minute timeout)

Detailed Guidance

1. Endpoint Selection Table: Comparison of when to use each endpoint
2. Operations Best Practices: Code examples showing bulk PATCH operations
3. Tracking Completion: Polling strategies and Event Subscription Service integration
4. Handling Failures: Multi-level status checking (provision → operation → extension)
5. Extension Failure Retry Strategy:
   • Identity extension fails → retry entire operation
   • Spend/Travel extensions fail → retry only failed extensions
6. Reducing Failure Rates: Pre-validation, error classification, exponential backoff

Why This Change Matters

The UPS API documentation previously lacked consolidated best practices, leading to:

• Suboptimal API usage patterns
• Higher failure rates due to validation issues
• Inefficient retry strategies
• Confusion about when to use bulk vs single-user endpoints

This addition provides developers with clear, actionable guidance to:

• ✅ Reduce API failures through pre-validation
• ✅ Implement efficient retry strategies
• ✅ Choose the right endpoint for their use case
• ✅ Handle failures at the appropriate granularity (identity vs spend/travel)

Content Source

Content is based on the official UPS API Best Practices documentation provided by the SAP Concur team.

Files Changed

• src/api-reference/user-provisioning/v4.user-provisioning.md (+236 lines)

Testing Checklist

• Content reviewed for technical accuracy
• Markdown formatting validated
• Code examples use proper syntax highlighting
• Section placement maintains logical documentation flow
• Links and cross-references work correctly
• Table formatting renders correctly

Screenshots

The new section includes:

• Tables comparing endpoint usage
• JSON code examples for bulk PATCH operations
• Multi-level failure handling guidance
• Polling vs webhook tracking strategies