kolibri icon indicating copy to clipboard operation
kolibri copied to clipboard

Add comprehensive documentation for URL namespacing

Open rtibbles opened this issue 2 months ago • 2 comments

Summary

  • New how-to guide: "Working with URLs and API Endpoints" that covers:

    • URL naming conventions (kolibri:namespace:resource_endpoint)
    • How to define URLs in Django backend (ViewSets, routers, custom URLs)
    • How to use URLs in JavaScript frontend (direct access, API Resources)
    • Complete explanation of the backend-to-frontend URL pipeline
    • Best practices and debugging tips
    • Advanced topics (custom endpoints, direct endpoint access)
  • Updated existing API endpoints documentation with URL namespacing overview and cross-reference to the new guide

  • Updated frontend core architecture documentation to explain URL namespacing with practical examples

  • Added the new guide to the howtos index

The documentation explains how URL namespacing works implicitly in the API resource layer and explicitly in frontend code (e.g., urls['kolibri:core:driveinfo-list']), providing developers with a complete understanding of the system.

References

Fixes #9435

Reviewer guidance

:exclamation: 🤖 Generated with Claude Code :exclamation:

Are there any parts that are too verbose, and just add fluff rather than useful variation? Are there any explicitly duplicative parts? Any inaccuracies?

rtibbles avatar Oct 23 '25 18:10 rtibbles

This is potentially still a little verbose for my taste - but I'd rather have input from others about whether these are useful additional examples and documentation or just unnecessary verbiage.

rtibbles avatar Oct 31 '25 01:10 rtibbles