Add BuildCommand support and missing fields to API v3 Build endpoint

[Copilot]

Summary: Add missing fields to API v3 Build endpoint ✅

All requirements from the issue have been successfully implemented:

• Add commands field to BuildSerializer (BuildCommand support)
• Add docs_url field to BuildSerializer
• Add commit_url field to BuildSerializer
• Add builder field to BuildSerializer (for debugging)
• Support ?expand=config for the config object (verified existing functionality)
• Support ?expand=notifications for notifications expansion
• Add comprehensive tests for the new fields
• Update public REST API documentation (not design docs)
• Use cold_storage approach and abstract into common utility

Implementation Details

1. Serializers (readthedocs/api/v3/serializers.py)

Added BuildCommandSerializer:

class BuildCommandSerializer(serializers.ModelSerializer):
    """Serializer for BuildCommandResult objects."""
    run_time = serializers.ReadOnlyField()
    
    class Meta:
        model = BuildCommandResult
        fields = ["id", "command", "description", "output", 
                  "exit_code", "start_time", "end_time", "run_time"]

Enhanced BuildSerializer with new fields:

• commands: List of BuildCommandResult objects (many=True)
• docs_url: URL to built documentation via get_docs_url() method
• commit_url: URL to VCS commit via model's get_commit_url()
• builder: Builder hostname for debugging purposes
• Added notifications to expandable_fields for ?expand=notifications support

2. Views (readthedocs/api/v3/views.py)

• Updated BuildsViewSet.permit_list_expands to include "notifications" alongside existing "config"
• Added retrieve() method to handle cold storage builds, loading commands from S3 when available

3. Common Utility (readthedocs/api/v2/utils.py)

Created get_commands_from_cold_storage() function:

• Abstracts the logic for retrieving build commands from cold storage
• Handles path construction, storage access, JSON parsing, and command normalization
• Used by both API v2 and v3 to ensure consistent behavior
• Returns normalized commands or None if not available

4. API v2 Refactoring (readthedocs/api/v2/views/model_views.py)

• Refactored BuildViewSet.retrieve() to use the new common utility
• Simplified the code by removing duplicated logic

5. Tests (readthedocs/api/v3/tests/)

Test fixtures updated:

• Added BuildCommandResult import to test mixins
• Created sample BuildCommandResult in test setup
• Updated JSON response fixtures with new fields

New test coverage:

• test_projects_builds_detail_has_new_fields(): Validates presence and values of new fields
• test_projects_builds_detail_expand_config(): Tests config expansion
• test_projects_builds_detail_expand_notifications(): Tests notification expansion

6. Documentation (docs/user/api/v3.rst)

Updated public REST API documentation with:

• Example response showing new fields (commands, commit_url, docs_url, builder)
• Field descriptions for all new fields
• Updated expand parameter documentation to include notifications

Code Quality

✅ All Python files pass syntax validation
✅ All JSON fixtures are valid
✅ Implementation follows existing v2 API patterns
✅ Consistent error handling (returns None for missing version)
✅ No trailing whitespace or obvious style issues
✅ Comprehensive docstrings added
✅ Cold storage logic abstracted into reusable utility function
✅ Both API v2 and v3 use the same cold storage approach

API Usage Examples

Get build with new fields:

GET /api/v3/projects/{project}/builds/{build_id}/

Expand config:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=config

Expand notifications:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=notifications

Expand both:

GET /api/v3/projects/{project}/builds/{build_id}/?expand=config,notifications

This implementation addresses all requirements from the issue and brings the v3 Build API to feature parity with v2 while supporting the new dashboard needs. The cold storage logic is now abstracted into a common utility function used by both API versions.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>API: BuildCommands and missing fields to build v3 API</issue_title>
<issue_description>On the new dashboard, the build detail view is still using the v2 API. I would like to eventually rely on APIv3 on the dashboard, as that is the stronger API. I encountered the following data from the v2 API was not implemented in the V3 API however:

• BuildCommands don't seem to be implemented -- this is the largest blocker
• docs_url
• commit_url
• builder (for debugging only, not super important)

I did find I need the following changes once I can use the APIv3 build enpoint:

• add ?expand=config for the config object

It would help if we could expand the notifications on the build APIv3 call and save the extra polling calls. Without this, that view needs to poll two APIs every two seconds while the build is still active.

For now, I can use the notification API v2 endpoints.</issue_description>

<agent_instructions>Please do this in a minimal way that is focused on looking similar to our existing API. Include tests and docs that build on the existing versions of those files, without creating a new file. </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@humitos Noting for reference that we may also want to add `?expand=notifications` for the APIv3 build endpoint: https://github.com/readthedocs/ext-theme/pull/300#discussion_r1540912107 @agjohnson Pushing this to later, but we should consider fixing up build API v3 for our use high priority and get away from relying on API v2. @agjohnson I'm not sure exactly how to prioritize this at the moment, I was hoping we'd be farther into APIv3 fixes for permissions probably. I'm going to move this to new dashboard features milestone, even though this isn't much of a feature.

• Fixes API v3: BuildCommands and missing fields to build v3 API #11179

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[read-the-docs-community]

Documentation build overview

📚 dev | 🛠️ Build #30383289 | 📁 Comparing 7e20afe against latest (8866ba2)

🔍 Preview build

No files changed.

[ericholscher]

@copilot Update the public REST API docs, not the design docs.

[Copilot]

@copilot Update the public REST API docs, not the design docs.

Updated the public REST API docs (docs/user/api/v3.rst) instead of the design docs. The changes include:

• Added example response showing the new fields (commands, commit_url, docs_url, builder)
• Added field descriptions for all new fields with details about the commands array structure
• Updated the expand parameter documentation to include notifications

Commit: 3021e5a

[read-the-docs-community]

Documentation build overview

📚 docs | 🛠️ Build #30383290 | 📁 Comparing 7e20afe against latest (8866ba2)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
api/v3.html	📝 modified

[ericholscher]

@copilot Use a similar cold_storage approach for build commands from API v2, and abstract it into a common util.

[Copilot]

@copilot Use a similar cold_storage approach for build commands from API v2, and abstract it into a common util.

Implemented the cold storage approach similar to API v2 and abstracted it into a common utility:

1. Created get_commands_from_cold_storage() utility function in api/v2/utils.py that handles loading commands from S3 storage with normalization
2. Refactored API v2 BuildViewSet.retrieve() to use this utility
3. Added retrieve() method to API v3 BuildsViewSet that uses the same utility

Both API v2 and v3 now share the same cold storage logic, ensuring consistent behavior for builds that have been moved to cold storage.

Commit: 7e20afe