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

• Pagination
  • all collection GET endpoints will support pagination. The default limit will be 50.

• Object Creation

  • support bulk creation for all resources

• Remove deprecated endpoints

  • envelopes/{envelopeId}/{month} (deprecated in feat: add grouped month endpoint #361)
  • budgets/{budgetId}/{month} (deprecated in feat: add grouped month endpoint #361)
  • budgets/{budgetId}/{month}/allocations (deprecated in feat: add new endpoints for allocation setting/deleting of a whole month #399)

• Remove

  • [x] month link for Envelopes (deprecated in feat: add grouped month endpoint #361) MonthConfigs are at /v3/envelopes/{id}/{month} now, so this link is updated to reflect that and kept.
  • month field in EnvelopeMonth as it is redundant. (deprecated in feat: add grouped month endpoint #361)
  • monthAllocations field in BudgetLinks as it is the same as groupedMonth, which will be renamed to month. (see feat: add new endpoints for allocation setting/deleting of a whole month #399 and the Rename section below). - feat: add /v3/budgets endpoints #858
  • budgeted field on the Month response, deprecated in feat: add more fields to month endpoint #500.
  • balance field from Budget, deprecated with Deprecate balance field on budgets #526. - feat: add /v3/budgets endpoints #858
  • reconciled flag from Transaction, see Reconciled flag for transaction needs to be settable for both source and destination account #528. (feat: add /v3/transactions collection endpoint with GET support #835)
  • Overspend handling: Remove. Overspend handling is a hack around good budgeting and will be removed. See Remove overspend handling #856.

• Rename

  • groupedMonth link for Budgets to month (possible due to the removal of the endpoints deprecated in feat: add grouped month endpoint #361) - feat: add /v3/budgets endpoints #858
  • hidden to archived everywhere (Categories, Accounts, Envelopes)

• Move

  • /v1/import to /v3/import/ynab4 and use /v3/import as a list endpoint for all import endpoints (Restructure import endpoints #465)
  • Integrate Allocation into MonthConfig #440 and remove the Allocation endpoint.

• Change

  • renameRuleId in /v1/import/ynab-import-preview to be null instead of the zero UUID when there is no rule that matched
  • Sort resources sensibly by default (alphabetically for most, by date for transactions)
  • 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:

• Update the go.mod version
• Remove overspend handling and add migration: Remove overspend handling #856
• Remove all v1 and v2 API routes, their methods, and functions
• Remove allocation model and move allocation from MonthConfig to MonthConfig create. Add migration to update MonthConfigs.
• Remove Overspend (Month Config) and Reconciled (Transaction) json marshalling overrides
• 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: Rename Hidden field to Archived for Envelopes, Categories and Accounts #871
• Check all TODO comments
• Check all "4.0.0" comments
• Check all "removed" comments to find things to be removed
• 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 #359 (comment)

[morremeyer]

v4.0.0 is merged with #915.