1. Context
• Company: Argent Bank, an online neobank.
• Team: Sébastien (front-end), project manager (Mila), CTO (Avery), backend already available (existing Swagger).
• Phase 2 deliverables: API document (OpenAPI/Swagger YAML) for transactions: monthly list grouped by account, detailed view, add/update/delete information attached to transactions; request/response examples and error codes.
• Starting point: Transactions page mockups, authentication and profile delivered in Phase 1, existing Swagger documentation for auth and profile routes.
2. Need
• Define secure REST routes to retrieve current-month transactions (grouped by account) and manage attached information (notes, categories, tags, labels, etc.).
• Provide a complete OpenAPI 3.0 specification exportable to YAML (Swagger Editor).
• Ensure performant responses with pagination/filtering, clear data schemas, and consistent error codes.
3. Client / Stakeholders
• Argent Bank end users who want to browse and annotate their monthly transactions.
• Backend team implementing routes against a clear, testable contract.
• QA/Product validating use cases via a mock server generated from the YAML.
4. Goals
4.1 Functional
• View all transactions for the current month, grouped by account.
• View details for a specific transaction.
• Add, update, or delete information attached to a transaction (without creating/deleting the transaction itself).
• Filter/search (category, type, amount, text) and sort (date/amount).
4.2 Technical
• Bearer JWT authentication; access restricted to the user’s accounts (401/403).
• Normalized pagination, sorting and filtering; period parameter via month=YYYY-MM (or from/to).
• Idempotent partial updates via PATCH, with auditing (logging).
• Reusable OpenAPI schemas, exhaustive examples, and standardized error codes (400/401/403/404/409/422/429/500).
5. Constraints / Challenges
• Consistency with the existing data model (accounts/transactions) and future compatibility (API versioning).
• Performance at scale (pagination, indexes, HTTP caching/ETag).
• Time zones and monthly boundaries (UTC vs local time).
• Concurrency (edit control via ETag/If-Match to prevent overwrites).
• Security (RBAC, rate limiting, strict payload validation, audit logging).
6. Process / Methodology
6.1 Analysis
• Review Transactions mockups and flows: monthly list per account → detail → annotate/edit → back to list.
• Proposed REST model: accounts and transactions resources, with list endpoints scoped to accounts and detail/edit endpoints scoped to transactions.
• Period parameters: month=YYYY-MM by default (current month), with optional from/to ISO 8601 for extended ranges.
6.2 Breakdown into GitHub issues
• Define the data model (Transaction, TransactionMetadata schemas).
• Specify endpoints and parameters (list, detail, patch metadata, delete a field).
• Write the OpenAPI YAML (components, reusable responses, error objects).
• Generate a mock server and validate via Swagger Editor + Schemathesis/Dredd.
• Backend technical review + adjustments (versioning /v1).
6.3 Architecture & logic
• Proposed endpoints (indicative naming):
- Monthly list (per account): GET /v1/accounts/{accountId}/transactions?month=YYYY-MM&page=&pageSize=&sort=&type=&category=&q=
- Transaction detail: GET /v1/transactions/{transactionId}
- Update attached info: PATCH /v1/transactions/{transactionId}/metadata (e.g., category, labels[], note, merchantName).
- Delete a specific piece of metadata: DELETE /v1/transactions/{transactionId}/metadata/{field} (e.g., note, category).
• Paginated responses wrapped in an envelope: items[], page, pageSize, total, links (optional HATEOAS).
• Grouping by account either handled in the UI (one call per account) or via an aggregate endpoint: GET /v1/reports/transactions?month=YYYY-MM&groupBy=account (optional).
6.4 Technical choices (rationale)
• Separate list (account-scoped) and detail (global) for stable URLs and efficient caching.
• Use PATCH for partial metadata updates (avoid resending the full resource).
• month=YYYY-MM covers most needs while keeping payloads lightweight; from/to reserved for advanced cases.
• Rich error semantics: 422 (validation), 409 (version conflict), 429 (rate limiting).
• ETag/If-Match for concurrency control, enabling 412 Precondition Failed.
6.5 Main flows
• List (current month): GET /v1/accounts/{accountId}/transactions?month=2025-11&page=1&pageSize=50&sort=-date → 200 with items[] + pagination metadata.
• Detail: GET /v1/transactions/tx123 → 200 with immutable properties + editable metadata.
• Add/update info: PATCH /v1/transactions/tx123/metadata body { "category": "Groceries", "note": "Weekend shopping" } → 200 + new ETag version.
• Delete info: DELETE /v1/transactions/tx123/metadata/note → 204 (or 200 with the updated resource).
6.6 Tests & quality
• Contract validation via Swagger Editor (lint), Schemathesis/Dredd (conformance tests).
• Full request/response examples (success/errors) embedded in the YAML to help QA and front-end (MSW).
• Consistent naming and HTTP statuses; reusable schemas in components/schemas and standard error responses in components/responses.
7. Analysis
• A clear separation between list/detail/metadata simplifies caching, security, and evolution. The month parameter frames the primary use case and keeps payloads small, while PATCH/DELETE provide straightforward granularity for annotations without altering the source transaction.
8. Technical decisions
• OpenAPI 3.0 (YAML) with factorized components (Transaction, TransactionMetadata, Error, Pagination).
• Standard Bearer auth, parametric pagination, sorting (sort=-date), filtering (type, category, q).
• Concurrency control with ETag; documented and exemplified errors 400/401/403/404/409/412/422/429/500.
9. Resolution logic
• Start from user journeys, map resources, define endpoints/params/schemas; validate with a mock server, test edge cases (empty months, empty filters, unknown metadata fields), iterate with the backend before freezing the v1 contract.
10. Stack used
• Spec: OpenAPI 3.0, Swagger Editor (YAML export).
• Mock/contract tests: Prism or Stoplight, Schemathesis/Dredd.
• Front (reference): React + Redux Toolkit / RTK Query to consume endpoints and manage cache/pagination.
11. Final outcome
• Swagger v1 YAML document ready for implementation, with schemas, parameters, examples, and error codes.
• Coherent endpoint set covering: monthly list per account, transaction detail, and CRUD of attached information (PATCH/DELETE).
• Strong foundation for backend implementation, QA testing, and front-end integration (generated types, MSW).