feat(`api2`): `Prefer: securedrop=x` limits response shape to minor version `2.x` #7703

cfm · 2025-10-31T18:55:19Z

Closes #7639 (see context there) by letting the client specify an API minor version for the response shape it expects. Currently we have four minor versions:

securedrop/securedrop/journalist_app/api2/__init__.py

Lines 30 to 34 in 00b1677

    
           # 0. Initial implementation 
        
           # 1. `Index` and `BatchResponse` include `journalists` 
        
           # 2. `Reply` and `Submission` objects include `interaction_count` 
        
           # 3. `BatchRequest` accepts `events` to process, with results returned in 
        
           #    `BatchResponse.events`

Test plan

Tests adequately exercise Prefer: securedrop=x versions defined so far.
The SecureDrop journalist app at develop works as expected without sending a Prefer header.

Checklist

This change accounts for:

any required additional documentation

I will add to #7713 (or a follow-up) once this this is merged.

any necessary AppArmor changes (added or removed application files)
any impact on new SecureDrop installs and upgrades
our dependency update policy

Copilot

Pull Request Overview

This PR implements API versioning support for the SecureDrop API v2, allowing clients to specify a preferred minor version via the Prefer header. The changes conditionally include or exclude certain fields based on the requested API minor version.

Added minor parameter to to_api_v2() methods across models to support versioning
Implemented version-based conditional field inclusion (e.g., interaction_count only in v2.2+)
Added logic to filter top-level response keys based on API minor version

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
securedrop/models.py	Updated `to_api_v2()` methods to accept `minor` parameter and conditionally include `interaction_count` field for API v2.2+
securedrop/journalist_app/api2/init.py	Added API minor version handling via `Prefer` header, conditional event processing for v2.3+, and response filtering based on client version

Comments suppressed due to low confidence (1)

securedrop/journalist_app/api2/init.py:142

Missing minor parameter in source.to_api_v2() call. This is inconsistent with other calls in the same function (lines 134, 149, 158, 165) and means sources requested directly won't respect the client's API version preference. Change to source.to_api_v2(minor).

            response.sources[source.uuid] = source.to_api_v2()

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

securedrop/models.py

cfm · 2025-11-02T17:13:25Z

securedrop/journalist_app/api2/__init__.py


        # Process events in snowflake order.
        for event in sorted(events, key=lambda e: int(e.id)):
            result = handler.process(event)


Event handlers will need to be passed minor so that they can version-check consistently:

- current_version = json_version(source.to_api_v2()) + current_version = json_version(source.to_api_v2(minor))

maybe we have it as a member variable on handler and turn the event handlers into normal methods instead of static ones?

I tried it out, and I realized that there's a separation I'd like to preserve, in order to keep the actual handler methods as close to pure functions on (event received, current server state) as possible.

securedrop/securedrop/journalist_app/api2/events.py

Lines 43 to 49 in f241f6b

def __init__(self, session: Session, redis: Redis) -> None:

"""

Configure the `EventHandler`. Attributes set here are for internal use

by the `EventHandler`; handler methods are static and do not have access

to them, which means they cannot influence the processing of a given

event.

"""

legoktm

Overall I like the direction; the conditionals are quite simple right now, if it does get much more complicated we might want to have some explicit serialization class.

legoktm · 2025-11-07T18:43:33Z

securedrop/journalist_app/api2/__init__.py


        # Process events in snowflake order.
        for event in sorted(events, key=lambda e: int(e.id)):
            result = handler.process(event)


maybe we have it as a member variable on handler and turn the event handlers into normal methods instead of static ones?

securedrop/journalist_app/api2/__init__.py

securedrop/models.py

Copilot

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

securedrop/tests/test_journalist_api2.py

securedrop/journalist_app/api2/__init__.py

Copilot

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

legoktm

Test plan checks out, LGTM. Left two nits, but if you don't want to address them, feel free to merge right away.

securedrop/journalist_app/api2/__init__.py

securedrop/models.py

…sion 2.x This avoids overloading the "Accept" header's syntax for content negotiation, since we don't care about its caching semantics.

…ns 2.1 ‒ 2.3 Thanks to ChatGPT.[^1] [^1]: https://chatgpt.com/share/691635a8-09a0-800f-a35f-a7ae98f9131e

legoktm

Thanks!

cfm added this to SecureDrop Oct 31, 2025

cfm moved this to In Progress in SecureDrop Oct 31, 2025

cfm requested a review from Copilot October 31, 2025 18:55

Copilot AI reviewed Oct 31, 2025

View reviewed changes

securedrop/models.py Outdated Show resolved Hide resolved

cfm force-pushed the 7639-apiv2-minor-versioning branch from 02fba8b to d3fe688 Compare October 31, 2025 18:58

cfm mentioned this pull request Oct 31, 2025

/api/v2/index: let the client specify types to return #7639

Closed

cfm requested a review from legoktm October 31, 2025 19:07

cfm self-assigned this Oct 31, 2025

cfm force-pushed the 7639-apiv2-minor-versioning branch 2 times, most recently from 671af27 to e670850 Compare October 31, 2025 19:37

cfm changed the title ~~feat(/data): Prefer: securedrop=x limits response shape to minor version 2.x~~ feat(/data): Prefer: securedrop=x limits response shape to minor version 2.x Nov 1, 2025

cfm mentioned this pull request Nov 1, 2025

API v2: further tighten typing and validation #7682

Closed

cfm commented Nov 2, 2025

View reviewed changes

cfm moved this from In Progress to Ready For Review in SecureDrop Nov 6, 2025

legoktm reviewed Nov 7, 2025

View reviewed changes

cfm moved this from Ready For Review to In Progress in SecureDrop Nov 12, 2025

cfm force-pushed the 7639-apiv2-minor-versioning branch 2 times, most recently from 44445c7 to 218f01b Compare November 13, 2025 19:57

cfm requested a review from Copilot November 13, 2025 19:58

Copilot started reviewing on behalf of cfm November 13, 2025 19:59 View session

Copilot finished reviewing on behalf of cfm November 13, 2025 20:02

Copilot AI reviewed Nov 13, 2025

View reviewed changes

cfm force-pushed the 7639-apiv2-minor-versioning branch from cfcfdb5 to 00b1677 Compare November 13, 2025 20:37

cfm requested a review from Copilot November 13, 2025 20:37

Copilot started reviewing on behalf of cfm November 13, 2025 20:37 View session

Copilot finished reviewing on behalf of cfm November 13, 2025 20:40

Copilot AI reviewed Nov 13, 2025

View reviewed changes

cfm force-pushed the 7639-apiv2-minor-versioning branch from 00b1677 to f241f6b Compare November 13, 2025 20:47

cfm changed the title ~~feat(/data): Prefer: securedrop=x limits response shape to minor version 2.x~~ feat: Prefer: securedrop=x limits v2 Journalist API response shape to minor version 2.x Nov 13, 2025

cfm marked this pull request as ready for review November 13, 2025 20:49

cfm requested a review from a team as a code owner November 13, 2025 20:49

cfm moved this from In Progress to Ready For Review in SecureDrop Nov 13, 2025

cfm assigned legoktm and unassigned cfm Nov 13, 2025

cfm requested a review from legoktm November 13, 2025 20:52

cfm force-pushed the 7639-apiv2-minor-versioning branch 2 times, most recently from 7ef0e42 to 88d5991 Compare November 14, 2025 01:39

cfm changed the title ~~feat: Prefer: securedrop=x limits v2 Journalist API response shape to minor version 2.x~~ feat(api2): Prefer: securedrop=x limits response shape to minor version 2.x Nov 14, 2025

cfm mentioned this pull request Nov 14, 2025

feat(api2): validate and freeze dataclasses #7716

Merged

9 tasks

legoktm previously approved these changes Nov 14, 2025

View reviewed changes

securedrop/journalist_app/api2/__init__.py Show resolved Hide resolved

securedrop/models.py Outdated Show resolved Hide resolved

securedrop/models.py Outdated Show resolved Hide resolved

legoktm moved this from Ready For Review to Under Review in SecureDrop Nov 14, 2025

cfm added 2 commits November 14, 2025 09:50

feat(api2): "Prefer: securedrop=x" limits response shape to minor ver…

bf7a273

…sion 2.x This avoids overloading the "Accept" header's syntax for content negotiation, since we don't care about its caching semantics.

test(test_api_minor_versions): check response shapes for minor versio…

e888fef

…ns 2.1 ‒ 2.3 Thanks to ChatGPT.[^1] [^1]: https://chatgpt.com/share/691635a8-09a0-800f-a35f-a7ae98f9131e

cfm dismissed legoktm’s stale review via e888fef November 14, 2025 17:51

cfm force-pushed the 7639-apiv2-minor-versioning branch from 88d5991 to e888fef Compare November 14, 2025 17:51

cfm requested a review from legoktm November 14, 2025 17:52

legoktm approved these changes Nov 17, 2025

View reviewed changes

legoktm added this pull request to the merge queue Nov 17, 2025

Merged via the queue into develop with commit d3e613a Nov 17, 2025
19 checks passed

github-project-automation bot moved this from Under Review to Done in SecureDrop Nov 17, 2025

legoktm deleted the 7639-apiv2-minor-versioning branch November 17, 2025 15:46

nathandyer removed this from SecureDrop Nov 17, 2025

This was referenced Nov 17, 2025

send Prefer: securedrop=x header for expected API version 2.x freedomofpress/securedrop-client#2830

Closed

docs(api2): document Prefer: securedrop=x header #7719

Merged

	# 0. Initial implementation
	# 1. `Index` and `BatchResponse` include `journalists`
	# 2. `Reply` and `Submission` objects include `interaction_count`
	# 3. `BatchRequest` accepts `events` to process, with results returned in
	# `BatchResponse.events`

	def __init__(self, session: Session, redis: Redis) -> None:
	"""
	Configure the `EventHandler`. Attributes set here are for internal use
	by the `EventHandler`; handler methods are static and do not have access
	to them, which means they cannot influence the processing of a given
	event.
	"""

feat(api2): Prefer: securedrop=x limits response shape to minor version 2.x #7703

feat(api2): Prefer: securedrop=x limits response shape to minor version 2.x #7703

Uh oh!

Conversation

cfm commented Oct 31, 2025 • edited by legoktm Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

cfm Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

legoktm Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

cfm Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

legoktm left a comment

Choose a reason for hiding this comment

Uh oh!

legoktm Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

legoktm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

legoktm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(`api2`): `Prefer: securedrop=x` limits response shape to minor version `2.x` #7703

feat(`api2`): `Prefer: securedrop=x` limits response shape to minor version `2.x` #7703

cfm commented Oct 31, 2025 •

edited by legoktm

Loading