v3 Planning

[morremeyer]

This issue documents the planned changes for v3 of the API.

There is no target date for a v3 completion, it will be introduced endpoint by endpoint.

Once all endpoints are available and the frontend has ceased usage of v1 and v2 endpoints, a breaking change removing v1 and v2 will be released.

Planned changes

• [x] Pagination

  • [x] all collection GET endpoints will support pagination. The default limit will be 50.

• [x] Object Creation

  • [x] support bulk creation for all resources

• [x] Remove deprecated endpoints

  • [x] envelopes/{envelopeId}/{month} (deprecated in #361)
  • [x] budgets/{budgetId}/{month} (deprecated in #361)
  • [x] budgets/{budgetId}/{month}/allocations (deprecated in #399)

• [x] Remove

  • ~[x] month link for Envelopes (deprecated in #361)~ MonthConfigs are at /v3/envelopes/{id}/{month} now, so this link is updated to reflect that and kept.
  • [x] month field in EnvelopeMonth as it is redundant. (deprecated in #361)
  • [x] monthAllocations field in BudgetLinks as it is the same as groupedMonth, which will be renamed to month. (see #399 and the Rename section below). - #858
  • [x] budgeted field on the Month response, deprecated in #500.
  • [x] balance field from Budget, deprecated with #526. - #858
  • [x] reconciled flag from Transaction, see #528. (#835)
  • [x] Overspend handling: Remove. Overspend handling is a hack around good budgeting and will be removed. See #856.

• [x] Rename

  • [x] groupedMonth link for Budgets to month (possible due to the removal of the endpoints deprecated in #361) - #858
  • [x] hidden to archived everywhere (Categories, Accounts, Envelopes)

• [x] Move

  • [x] /v1/import to /v3/import/ynab4 and use /v3/import as a list endpoint for all import endpoints (#465)
  • [x] #440 and remove the Allocation endpoint.

• [x] Change

  • [x] renameRuleId in /v1/import/ynab-import-preview to be null instead of the zero UUID when there is no rule that matched
  • [x] Sort resources sensibly by default (alphabetically for most, by date for transactions)
  • [x] Make Month Configs easier to use: Always allow PATCH requests and transparenty create the resource if it does not exist yet.

[morremeyer]

Updated this to be v3 planning since I forgot pagination in v2. Therefore, v2 will be deprecated with the release of the corresponding API v3 enpoints.

API v1 and API v2 will be removed when the frontend does not use them anymore.

[morremeyer]

Notes for the 4.0.0 release changes:

• [x] Update the go.mod version
• [x] Remove overspend handling and add migration: #856
• [x] Remove all v1 and v2 API routes, their methods, and functions
• [x] Remove allocation model and move allocation from MonthConfig to MonthConfig create. Add migration to update MonthConfigs.
• [x] Remove Overspend (Month Config) and Reconciled (Transaction) json marshalling overrides
• [x] Rename Hidden field to Archived in Models for Account, Category, and Envelope. Add migration. Remove Hidden -> Archived code in the GET filtering for collection endpoints and in the gorm hooks: #871
• [x] Check all TODO comments
• [x] Check all "4.0.0" comments
• [x] Check all "removed" comments to find things to be removed
• [x] Update upgrading docs

[morremeyer]

All v3 endpoints have been released. There will be a transition period until the frontend uses v3 everywhere, after which the backend will have a major release, removing API v1 and v2 and implementing the changes mentioned in https://github.com/envelope-zero/backend/issues/359#issuecomment-1837433945

[morremeyer]

v4.0.0 is merged with #915.