API Tags Documentation Index

Complete documentation for the Python.org API OpenAPI tag structure and organization.

Overview

The Python.org API uses optimized OpenAPI tags to organize 50+ endpoints into logical, discoverable categories. This documentation provides complete guidance on the tag structure, implementation, and maintenance.

Core Problem Solved

Before: 100+ fragmented tags making API documentation hard to navigate

  • Developers struggled to find relevant endpoints

  • Tag names were inconsistent (kebab-case vs Title Case)

  • Related endpoints were scattered across different tag categories

  • Render controllers polluted the public API documentation

After: 50 logically grouped tags organized by developer journey

  • Clear, consistent naming (Title Case with spaces)

  • Related resources grouped together

  • Intuitive discovery flow (auth → users → content → features)

  • Render controllers hidden from public docs

Documentation Files

1. API_TAGS_STRUCTURE.md (Primary Reference)

Purpose: Detailed tag definitions and rationale

Contains:

  • All 50 recommended tags with descriptions

  • Which controllers should use each tag

  • Design principles behind the structure

  • Ordering strategy for Scalar UI

  • Complete migration notes

When to Use: When you need to understand WHY a tag exists and what endpoints belong in it.

Size: 15 KB | Read Time: 15-20 minutes

2. API_TAGS_QUICK_REF.md (Quick Lookup)

Purpose: Quick reference table for tag assignments

Contains:

  • Reference table: Tag # → Name → Controllers → Key Endpoints

  • Tag groups by category (Core, Content, Downloads, etc.)

  • Render controllers to exclude from public API

  • Implementation checklist

  • Common migration examples

When to Use: When you need to quickly look up which tag to use for a controller or see the complete tag mapping.

Size: 8.1 KB | Read Time: 5-10 minutes

3. API_TAGS_HIERARCHY.txt (Visual Reference)

Purpose: Visual hierarchy diagram of tag organization

Contains:

  • ASCII art showing tag relationships

  • Nesting structure (Events → Calendars → Categories)

  • Core vs Admin separation

  • Statistics and benefits

  • Excluded render controllers clearly marked

When to Use: When you want to visualize how tags relate to each other and understand the overall structure at a glance.

Size: 21 KB | Read Time: 10-15 minutes

4. API_TAGS_IMPLEMENTATION.md (Implementation Guide)

Purpose: Step-by-step implementation instructions

Contains:

  • Phase 1: Audit current implementation

  • Phase 2: Update controller tags (with examples for each domain)

  • Phase 3: Configure OpenAPI tags

  • Phase 4: Exclude render controllers

  • Phase 5: Testing & validation

  • Phase 6: Documentation & communication

  • Complete checklist and rollback plan

When to Use: When you’re ready to implement the tag structure in the codebase.

Size: 18 KB | Read Time: 20-30 minutes

5. API_TAGS_BEST_PRACTICES.md (Maintenance Guide)

Purpose: Guidelines for maintaining and extending the tag structure

Contains:

  • Naming conventions (Title Case, concise, specific)

  • Controller organization guidelines

  • When and how to add new tags

  • Tag refactoring checklist

  • OpenAPI configuration best practices

  • Testing tag assignments

  • Common patterns and troubleshooting

  • Future improvement ideas

When to Use: When you’re adding new controllers/tags or maintaining the existing structure.

Size: 15 KB | Read Time: 15-20 minutes

6. API_TAGS_INDEX.md (This File)

Purpose: Navigation and overview of all tag documentation

Size: ~3 KB

Quick Start

For Implementation

  1. Start with API_TAGS_QUICK_REF.md to understand the current tag assignments

  2. Read API_TAGS_STRUCTURE.md to understand the rationale

  3. Follow API_TAGS_IMPLEMENTATION.md phase by phase

  4. Reference API_TAGS_BEST_PRACTICES.md during implementation

For Maintenance

  1. Check API_TAGS_BEST_PRACTICES.md for naming and organization guidelines

  2. Update API_TAGS_QUICK_REF.md when adding new tags

  3. Use the checklist in API_TAGS_BEST_PRACTICES.md for consistency

For Understanding

  1. Start with API_TAGS_HIERARCHY.txt for visual overview

  2. Read API_TAGS_STRUCTURE.md for detailed information

  3. Reference API_TAGS_QUICK_REF.md for specific tag mappings

Tag Structure Summary

Tag Counts by Category

Category

Tags

Examples

Core API

6

Authentication, Users, User Memberships, User Groups, Search, Mailing

Content

5

Pages, Documents, Images, Banners, Code Samples

Downloads

3

Operating Systems, Python Releases, Release Files

Events

5

Events, Calendars, Categories, Locations, Occurrences

Community

2

User Groups & Communities, Community Content

Content Discovery

4

Blogs, Blog Feeds, Success Stories, Categories

Jobs

4

Jobs, Job Types, Job Categories, Review Comments

Business

4

Sponsors, Sponsorship Levels, Sponsorships, Companies

Governance

5

Work Groups, Minutes, Nominations, Nominees, Elections

Administration

12

Dashboard, Users, Pages, Events, Jobs, Sponsors, Blogs, Logs, Email, Tasks, Settings

Total Public

50

Design Principles

  1. Logical Grouping: Related endpoints organized into coherent categories

  2. Developer Journey: Tags ordered by typical workflow (auth → content → features)

  3. Consistency: Title Case with spaces throughout

  4. Admin Isolation: Administrative endpoints clearly separated

  5. Render Exclusion: HTML controllers hidden from public API docs

Key Improvements Over Current Structure

Aspect

Before

After

Total Tags

100+

50

Naming Convention

Mixed (kebab-case, Title Case)

Consistent Title Case

Navigation

Fragmented, hard to discover

Logical, grouped by workflow

Render Controllers

Polluting public API

Hidden (internal tag)

Admin Organization

No clear grouping

Grouped with “Admin” prefix

Related Resources

Scattered

Adjacent for discovery

Implementation Status

Current (As of This Documentation)

  • Documentation created and organized

  • 50 tags defined with clear descriptions

  • Tag hierarchy designed and documented

  • Implementation guide prepared

Next Steps

  1. Review: Team reviews the proposed structure

  2. Implement: Follow API_TAGS_IMPLEMENTATION.md phase by phase

  3. Test: Verify in Scalar UI and run test suite

  4. Deploy: Roll out to production

  5. Monitor: Track developer feedback and usage patterns

Key Statistics

  • Total Documentation: ~77 KB

  • Total Tags: 50 public + 1 internal + 1 for render exclusion

  • Controller Files: 27 files to update

  • Documentation Files: 6 files (including this index)

  • Estimated Implementation Time: 4-6 hours

  • Estimated Testing Time: 2-3 hours

FAQs

Q: Why 50 tags? Couldn’t we have fewer?

A: 50 tags represent a balance between:

  • Too few (5-10): Developers can’t find specific endpoints

  • Too many (100+): Overwhelming navigation, hard to discover

50 tags group related endpoints while keeping categories distinct and discoverable.

Q: What about future growth?

A: The structure is designed to scale. New tags can be added by:

  1. Finding a logical parent category (e.g., add to “Community Content”)

  2. Creating a related tag if genuinely new (e.g., “Community Events”)

  3. Following naming conventions (Title Case, descriptive, concise)

See API_TAGS_BEST_PRACTICES.md for detailed guidance.

Q: Should we use sub-tags or nested categories?

A: No. OpenAPI spec doesn’t support nested tags. Instead:

  • Use related prefixes (Event Calendars, Event Categories)

  • Keep related tags adjacent in the list

  • Update documentation to show relationships

Q: How do we exclude render controllers?

A: Two options:

  1. Mark with “internal” tag: tags = ["internal"]

  2. Exclude from schema: include_in_schema = False

See API_TAGS_IMPLEMENTATION.md Phase 4 for details.

Document History

Version

Date

Changes

1.0

2025-11-27

Initial structure and documentation

Contact & Questions

For questions about the API tag structure:

  1. Check the relevant documentation file (see “Quick Start” section above)

  2. Review “Best Practices” section for common patterns

  3. Consult “Troubleshooting” in API_TAGS_BEST_PRACTICES.md

Contributing

When adding new controllers or tags:

  1. Follow naming conventions in API_TAGS_BEST_PRACTICES.md

  2. Update API_TAGS_QUICK_REF.md with new tag

  3. Update API_TAGS_STRUCTURE.md if adding new category

  4. Update API_TAGS_HIERARCHY.txt if structural change

  5. Reference these updates in your PR description

Total Documentation: 6 files | 77 KB | ~90 minutes read time (all files)

Quick Implementation: 4-6 hours from start to production deployment

Maintenance: 5-10 minutes per new tag following best practices