Optimal API Documentation Tag Structure

This document defines the recommended OpenAPI tag hierarchy for the Python.org API documentation, optimized for developer experience in Scalar UI.

Design Principles

  1. Logical Grouping: Related endpoints organized into coherent, discoverable categories

  2. User Journey: Tags ordered by typical developer workflow (auth → users → content → discovery)

  3. Clarity: Consistent naming with Title Case spaces for maximum readability in Scalar

  4. Admin Separation: Administrative endpoints clearly separated and lower priority

  5. Exclusions: Render controllers excluded from public API documentation

Implementation Guidelines

OpenAPI Tag Definition Structure

Each tag should be defined in the Litestar OpenAPI configuration with:

Tag(
    name="Tag Name",
    description="Concise description of what endpoints in this group do",
    external_docs=ExternalDocumentation(
        url="https://docs.python.org/path/to/docs",
        description="Learn more about this feature"
    ) if applicable
)

Controller Implementation

Update controller tags from the current structure:

# Before (too granular)
class JobTypeController(Controller):
    tags = ["job-types"]

# After (grouped under primary resource)
class JobTypeController(Controller):
    tags = ["Job Types"]

Hide Render Endpoints from Public API

Mark render controllers to exclude from public documentation:

# Render controllers should NOT appear in public API docs
class JobRenderController(Controller):
    tags = ["internal"]  # or use OpenAPI exclude mechanism

Ordering Strategy for Scalar UI

Tags are presented to users in the order they appear in the OpenAPI tags array. Recommended order:

  1. Authentication - Required first by developers

  2. Users → User Memberships → User Groups - User management flow

  3. Pages → Documents → Images → Banners → Code Samples - Content resources

  4. Operating Systems → Python Releases → Release Files - Download-related

  5. Events → Calendars → Categories → Locations → Occurrences - Event management flow

  6. User Groups & Communities → Community Content - Community discovery

  7. Blogs → Blog Feeds → Success Stories - Content discovery

  8. Jobs → Job Types → Job Categories → Job Review Comments - Job management

  9. Sponsors → Sponsorship Levels → Sponsorships → Companies - Sponsorship flow

  10. Work Groups → Meeting Minutes → Nominations → Nominees → Elections - Governance

  11. Search - Aggregate discovery

  12. Mailing Lists - Communication

  13. Admin Dashboard → Admin Users → Admin Pages → … - Administrative tools

Benefits of This Structure

  • Reduced Cognitive Load: Developers see 50 focused tags instead of 100+ fragmented ones

  • Logical Flow: Follows typical developer journey from auth → content → features

  • Related Grouping: Sub-resources (e.g., Event → Calendar → Category) are adjacent

  • Admin Isolated: Administrative endpoints clearly separated and deprioritized

  • Render Excluded: Internal render controllers hidden from public documentation

  • Scalable: Easy to add new tags to appropriate categories as platform grows

  • Readable: Title Case with spaces much more readable in Scalar UI than kebab-case

Migration Notes

  1. Update all controller tags assignments to match this structure

  2. Configure OpenAPI tags list in main application config

  3. Add include_in_schema=False to render controllers or mark them “internal”

  4. Test in Scalar UI to verify grouping and ordering

  5. Consider adding brief external documentation links where applicable

  6. Monitor usage patterns to validate grouping logic