feat(usage): deprecate legacy periodic-usage endpoints [MOI-7252]

[adnilaM (malinda1986)]

Ticket: https://contentful.atlassian.net/browse/MOI-7252

Summary by Bito

This PR deprecates the legacy organization_periodic_usages and space_periodic_usages API endpoints in the Contentful Management Java SDK by adding Daniel Edeling (@deprecated) annotations and Javadoc warnings across five files, indicating these endpoints will be removed on 2027-02-28.

Detailed Changes

• Added Daniel Edeling (@deprecated) annotation and deprecation Javadoc to both sync and async fetchAll methods in ModuleOrganizationUsage.java, covering the deprecated GET /organizations/{organization_id}/organization_periodic_usages endpoint
• Added Daniel Edeling (@deprecated) annotation and deprecation Javadoc to both sync and async fetchAll methods in ModuleSpaceUsage.java, covering the deprecated GET /organizations/{organization_id}/space_periodic_usages endpoint
• Added Daniel Edeling (@deprecated) annotation and deprecation Javadoc to all fetchAll method overloads in ServiceOrganizationUsage.java Retrofit interface definitions
• Added Daniel Edeling (@deprecated) annotation and deprecation Javadoc to all fetchAll method overloads in ServiceSpaceUsage.java Retrofit interface definitions
• Deprecated the CMAUsage model class as it is backed by the legacy endpoints being phased out

[bito-code-review]

Changelist by Bito

This pull request implements the following key changes.

Key Change	Files Impacted	Summary
Feature Improvement - Deprecation of Legacy Periodic Usage API Endpoints	ModuleOrganizationUsage.java, ModuleSpaceUsage.java, ServiceOrganizationUsage.java, ServiceSpaceUsage.java, CMAUsage.java	Added Daniel Edeling (@deprecated) annotations and Javadoc warnings across usage-related classes indicating legacy organization_periodic_usages and space_periodic_usages endpoints will return 410 Gone after 2027-02-28.

[bito-code-review]

Functional Validation by Bito

Source	Requirement / Code Area	Status	Notes
MOI-7252	Add Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag to ModuleOrganizationUsage#fetchAll methods (sync + async) in ModuleOrganizationUsage.java with sunset date 2027-02-28	✅ Met	Both sync and async fetchAll methods in src/main/java/com/contentful/java/cma/ModuleOrganizationUsage.java now have Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag with sunset date 2027-02-28, matching the pattern from contentful-management.js (PR #3088).
MOI-7252	Add Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag to ModuleSpaceUsage#fetchAll methods (sync + async) in ModuleSpaceUsage.java with sunset date 2027-02-28	✅ Met	Both sync and async fetchAll methods in src/main/java/com/contentful/java/cma/ModuleSpaceUsage.java now have Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag with sunset date 2027-02-28, matching the pattern from contentful-management.js (PR #3088).
MOI-7252	Add Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag to ServiceOrganizationUsage#fetchAll methods (both overloads) in ServiceOrganizationUsage.java with sunset date 2027-02-28	✅ Met	Both fetchAll method overloads in src/main/java/com/contentful/java/cma/ServiceOrganizationUsage.java now have Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag with sunset date 2027-02-28, matching the pattern from contentful-management.js (PR #3088).
MOI-7252	Add Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag to ServiceSpaceUsage#fetchAll methods (both overloads) in ServiceSpaceUsage.java with sunset date 2027-02-28	✅ Met	Both fetchAll method overloads in src/main/java/com/contentful/java/cma/ServiceSpaceUsage.java now have Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag with sunset date 2027-02-28, matching the pattern from contentful-management.js (PR #3088).
MOI-7252	Add Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag to CMAUsage model class in model/CMAUsage.java with sunset date 2027-02-28	✅ Met	The CMAUsage model class in src/main/java/com/contentful/java/cma/model/CMAUsage.java now has Daniel Edeling (@deprecated) annotation and Javadoc Daniel Edeling (@deprecated) tag with sunset date 2027-02-28, matching the pattern from contentful-management.js (PR #3088).

[bito-code-review]

Impact Analysis by Bito

Interaction Diagram

sequenceDiagram
participant App as Application<br/>🔄 Updated | ●○○ Low
participant Client as CMAClient<br/>🔄 Updated | ●○○ Low
participant ModOrg as ModuleOrganizationUsage<br/>🔄 Updated | ●●○ Medium
participant ModSpace as ModuleSpaceUsage<br/>🔄 Updated | ●●○ Medium
participant SvcOrg as ServiceOrganizationUsage<br/>🔄 Updated | ●●○ Medium
participant SvcSpace as ServiceSpaceUsage<br/>🔄 Updated | ●●○ Medium
participant Model as CMAUsage Model<br/>🔄 Updated | ●●○ Medium
participant API as Contentful REST API<br/>🔄 Updated | ●●○ Medium
Note over ModOrg, ModSpace: Deprecated annotation added<br/>Endpoints return 410 Gone after 2027-02-28
App->>Client: Get usage module instance
Client->>ModOrg: Instantiate ModuleOrganizationUsage
Client->>ModSpace: Instantiate ModuleSpaceUsage
App->>ModOrg: Call fetchAll(orgId, query)
ModOrg->>SvcOrg: Delegate HTTP request
SvcOrg->>API: GET organization_periodic_usages
Note over API: Returns CMAArray of CMAUsage objects
API-->>SvcOrg: Flowable response
SvcOrg-->>ModOrg: CMAArray<CMAUsage>
ModOrg-->>App: CMAArray<CMAUsage>
App->>ModSpace: Call fetchAll(orgId, query)
ModSpace->>SvcSpace: Delegate HTTP request
SvcSpace->>API: GET space_periodic_usages
API-->>SvcSpace: Flowable response
SvcSpace-->>ModSpace: CMAArray<CMAUsage>
ModSpace-->>App: CMAArray<CMAUsage>

Loading

---

This PR marks the organization and space periodic usage API endpoints as deprecated across the SDK. The Daniel Edeling (@deprecated) annotation is added to 5 files: ModuleOrganizationUsage, ModuleSpaceUsage, ServiceOrganizationUsage, ServiceSpaceUsage, and CMAUsage model. These endpoints will return 410 Gone responses after February 28, 2027. No upstream or downstream cross-repo impact detected. Applications using the CMAClient to fetch usage data will now see deprecation warnings at compile time, prompting migration to the new Usage API.

Cross-Repository Impact Analysis

What Changed	Impact of Change	Suggested Review Actions
Added Daniel Edeling (@deprecated) annotations and Javadoc to all Usage API public surface (CMAUsage class, ModuleOrganizationUsage, ModuleSpaceUsage, ServiceOrganizationUsage, ServiceSpaceUsage methods). No functional code removed.	- ⚠️ unverified — No verified cross-repo consumers found: BitoAIArchitect does not index contentful-management.java repository. Local code search confirms all usages are intra-repo: CMAClient.java exposes organizationUsage() and spaceUsage() entry points; UsageTest.kt exercises the deprecated endpoints. No external repositories were verifiable as consumers via MCP.	- Verify whether any other repositories in the org import or depend on this contentful-management.java SDK. If so, those consumers should be warned about the 2027-02-28 deprecation deadline. - Confirm Contentful's new Usage API (replacement for the deprecated endpoints) is available and documented so SDK users know what to migrate to. - Consider adding a CHANGELOG or release-note entry for this deprecation so downstream SDK consumers are informed.

Code Paths Analyzed

Impact:
Low-risk deprecation marking only. Adds Daniel Edeling (@deprecated) annotations to 4 public types and 8 public methods. No functional changes — all methods remain callable with identical signatures. Existing tests (UsageTest.kt) continue to pass without modification.

Flow:
CMAClient exposes organizationUsage() → ModuleOrganizationUsage → ServiceOrganizationUsage → HTTP GET /organizations/{id}/organization_periodic_usages. Parallel path for spaceUsage() → ModuleSpaceUsage → ServiceSpaceUsage → HTTP GET /organizations/{id}/space_periodic_usages. Both REST endpoints deprecated (2027-02-28 removal).

Direct Changes (Diff Files):
• src/main/java/com/contentful/java/cma/ModuleOrganizationUsage.java [13, 25] — Added Daniel Edeling (@deprecated) annotation and Javadoc to both public fetchAll() method overloads (sync RxJava and async callback variants)
• src/main/java/com/contentful/java/cma/ModuleSpaceUsage.java [42, 54] — Added Daniel Edeling (@deprecated) annotation and Javadoc to both public fetchAll() method overloads (sync RxJava and async callback variants)
• src/main/java/com/contentful/java/cma/ServiceOrganizationUsage.java [72, 83] — Added Daniel Edeling (@deprecated) annotation and Javadoc to both Retrofit interface methods for the organization_periodic_usages endpoint
• src/main/java/com/contentful/java/cma/ServiceSpaceUsage.java [101, 112] — Added Daniel Edeling (@deprecated) annotation and Javadoc to both Retrofit interface methods for the space_periodic_usages endpoint
• src/main/java/com/contentful/java/cma/model/CMAUsage.java [131] — Added Daniel Edeling (@deprecated) annotation and Javadoc at class level, marking the model as deprecated along with the endpoints that return it

Repository Impact:
• CMAClient entry points (organizationUsage(), spaceUsage()): These public module accessors return types that now carry Daniel Edeling (@deprecated) — callers using them will receive compiler warnings. No behavioral change.
• UsageTest.kt (test suite for usage endpoints): Tests continue to exercise the deprecated endpoints. No test changes were made, which is appropriate — tests validate functionality until the endpoint is actually removed in 2027.
• All exported types and methods in the usage module: Every public-facing type in the usage module (CMAUsage, ModuleOrganizationUsage, ModuleSpaceUsage, their public methods) now carries Daniel Edeling (@deprecated), giving SDK consumers clear compiler-time warnings.

Cross-Repository Dependencies:
• None.

Database/Caching Impact:
• None

API Contract Violations:
• No API contract violations. Signatures are unchanged. The deprecation is a semantic warning — callers receive a compiler warning but no runtime behavior change until the endpoint is actually removed (2027-02-28).

Infrastructure Dependencies:
• No infrastructure changes. The Retrofit HTTP interface definitions (ServiceOrganizationUsage, ServiceSpaceUsage) remain structurally identical — only annotations added.

Additional Insights:
• Deprecation timeline consistency: Both deprecated endpoints share the same removal date (2027-02-28) and the same migration target (new Usage API). This is consistent and clear. The Javadoc should ideally include a link to the new Usage API documentation for users to reference during migration.
• Missing migration guidance: The deprecation Javadoc states 'deprecated in favor of the new Usage API' but does not specify what that new API is called or how to migrate. Consider adding a see (@see) reference or a link to Contentful's documentation for the replacement API so users know what to adopt.

Testing Recommendations

Frontend Impact:
• None.

Service Integration:
• Verify existing UsageTest.kt test cases (testFetchOrganizationUsageAll, testFetchSpaceUsageAll, testFetchAllOrganizationUsageWithQuery, testFetchAllSpaceUsageWithQuery) still pass — they exercise the deprecated endpoints which should remain functional until 2027-02-28.
• Add a new test (or update existing ones) that confirms Daniel Edeling (@deprecated) annotations compile correctly on CMAUsage, ModuleOrganizationUsage, and ModuleSpaceUsage — e.g., test that the Java compiler emits deprecation warnings in the expected call patterns.

Data Serialization:
• None.

Privacy Compliance:
• None.

Backward Compatibility:
• Confirm that callers of organizationUsage().fetchAll() and spaceUsage().fetchAll() can continue to use the methods at runtime. The deprecation is compile-time only; no runtime behavior is changed. This is safe for backward compatibility.
• When the actual removal occurs (post-2027-02-28), a major version bump will be required — update CHANGELOG to reflect this so SDK consumers know to expect breaking changes in the next major version.

OAuth Functionality:
• None

Cross-Service Communication:
• Validate that the deprecated REST endpoints (/organizations/{id}/organization_periodic_usages and /organizations/{id}/space_periodic_usages) still return expected HTTP 200 responses — the deprecation does not imply the endpoints are non-functional yet.

Reliability Testing:
• None

Additional Insights:
• Add a CHANGELOG entry for this deprecation: 'Deprecated usage endpoints (organization_periodic_usages, space_periodic_usages) scheduled for removal on 2027-02-28. Migrate to new Usage API.' This informs downstream SDK consumers who may not read Javadoc.
• Consider publishing a migration guide or updating the SDK README with instructions for adopting the replacement Usage API, since the deprecation message references an unnamed 'new Usage API' without specifics.

_{Analysis based on known dependency patterns and edges. Actual impact may vary.}

[bito-code-review]

Code Review Agent Run #cc5538

Actionable Suggestions - 1

• src/main/java/com/contentful/java/cma/model/CMAUsage.java - 1

  • Deprecation notice inconsistent · Line 6-8

Additional Suggestions - 1

• src/main/java/com/contentful/java/cma/ModuleSpaceUsage.java - 1

  • Annotation style inconsistency · Line 44-44
    The `@Deprecated` annotation placement at line 44 has a blank line before and after it, diverging from the established style in `ModuleOrganizationUsage` (lines 44, 77) where `@Deprecated` is placed inline immediately before `public` with no blank lines. For consistent deprecation signaling across both deprecated usage modules, align the annotation style.

Review Details

• Files reviewed - 5 · Commit Range: b660fe0..b660fe0

  • src/main/java/com/contentful/java/cma/ModuleOrganizationUsage.java
  • src/main/java/com/contentful/java/cma/ModuleSpaceUsage.java
  • src/main/java/com/contentful/java/cma/ServiceOrganizationUsage.java
  • src/main/java/com/contentful/java/cma/ServiceSpaceUsage.java
  • src/main/java/com/contentful/java/cma/model/CMAUsage.java
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Java-google-format (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers a full AI review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

✅ Review Settings Overridden

Status: Overridden Successfully

Guidelines:

• Accepted:

  • General : Review Posture, Repo Truth And Alignment, Domain Invariants

Note: Extra guidelines beyond 3 general purpose guidelines and 1 language specific guideline per language are not processed. Guidelines are fetched from the source branch.

[adnilaM (malinda1986)]

Re: the "Additional Suggestions" item flagging an annotation-style inconsistency in ModuleSpaceUsage.java (line 44, blank lines around @Deprecated) — checked the file directly and this doesn't reproduce. Line 43 is the Javadoc's closing */, line 44 is @Deprecated, line 45 is public ... fetchAll(, all adjacent with no blank lines. It already matches ModuleOrganizationUsage's style exactly, including the async nested method (line 77 here vs. the equivalent in ModuleOrganizationUsage). No change made for this one — it appears to be a false positive against the actual diff.

[bito-code-review]

Code Review Agent Run #3a6b08

Actionable Suggestions - 0

Review Details

• Files reviewed - 5 · Commit Range: 73ae393..73ae393

  • src/main/java/com/contentful/java/cma/ModuleOrganizationUsage.java
  • src/main/java/com/contentful/java/cma/ModuleSpaceUsage.java
  • src/main/java/com/contentful/java/cma/ServiceOrganizationUsage.java
  • src/main/java/com/contentful/java/cma/ServiceSpaceUsage.java
  • src/main/java/com/contentful/java/cma/model/CMAUsage.java
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Java-google-format (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers a full AI review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by