@lunch-money/developer-docs 2.11.0-preview.10

package/v2/docs/intro-to-v2.md

@@ -0,0 +1,117 @@
+# v2 API Overview
+
+Welcome to the Lunch Money v2 API. This page covers the core concepts you need to work with the API effectively — authentication, response shapes, naming conventions, error handling, and more. If you're migrating from v1, see the [Migration Guide](./migration-guide.md).
+
+## Authentication
+
+All API requests require a Bearer token in the `Authorization` header:
+
+```http
+Authorization: Bearer YOUR_ACCESS_TOKEN
+```
+
+Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money developers page</a>. See the [Getting Started guide](/v2/getting-started) for a step-by-step walkthrough including how to create a test budget.
+
+## Base URL
+
+```
+https://api.lunchmoney.dev/v2
+```
+
+## Response Shapes
+
+The v2 API uses consistent HTTP status codes and response bodies across all endpoints.
+
+### Successful responses
+
+- **GET** → `200 OK`. Response body contains either a single object or an array property named after the endpoint (e.g., `{ "transactions": [...] }`).
+- **POST** → `201 Created`. Response body contains the complete created object including system-defined properties like `id` and `created_at`.
+- **PUT** → `200 OK`. Response body contains the complete updated object.
+- **DELETE** → `204 No Content`. No response body.
+
+### Error responses
+
+All errors return an appropriate 4XX status code — the v2 API never returns an error inside a `200 OK` response.
+
+| Code | Meaning |
+|------|---------|
+| `400` | Bad Request — invalid parameters or request body |
+| `401` | Unauthorized — missing or invalid Bearer token |
+| `404` | Not Found — the requested object does not exist |
+| `422` | Unprocessable Content — request is valid but cannot be fulfilled (e.g., deleting a category with dependents) |
+| `429` | Too Many Requests — rate limit exceeded; response includes a `Retry-After` header. See the [Rate Limiting guide](/v2/rate-limits). |
+
+All error responses share a consistent body format:
+
+```json
+{
+  "message": "Overall error description",
+  "errors": [
+    { "errMsg": "Specific error about a parameter or field" }
+  ]
+}
+```
+
+> [!NOTE] Atomic Operations
+> When a request fails, no part of it is applied to your data. For example, if one transaction in a bulk insert has a validation error, none of the transactions in that request are inserted. Fix the errors and retry — you don't need to worry about partial duplicates.
+>
+> If a request has multiple validation errors, the response will attempt to list as many as possible, but it is not guaranteed to catch all errors in a single response.
+
+### Request validation
+
+The v2 API validates all requests strictly. A `400` is returned if the request includes unexpected parameters, missing required fields, fields with invalid values, or unexpected properties in the request body. This makes it easier to catch mistakes during development.
+
+## Naming Conventions
+
+Object properties follow consistent rules across the entire API:
+
+- Properties that belong to the object itself use simple names: `id`, `name`, `status`
+- Properties that reference related objects include the object type: `category_id`, `tag_ids`, `manual_account_id`
+- Timestamps end in `_at`: `created_at`, `updated_at`, `archived_at`
+- Lists of IDs include the type: `tag_ids` (not `tags`)
+- Child objects of the same type are always in a `children` property
+- All `id` fields are `integer` type (not `number`)
+
+## Amounts, Balances & Sign Convention
+
+The v2 API uses a consistent set of properties — `amount`, `balance`, `currency`, and `to_base` — across all objects that deal with money. See the [Amounts & Balances guide](/v2/amounts-and-balances) for a full explanation of how these properties work, including the sign convention and multi-currency support.
+
+## Hydrated vs. Non-Hydrated Responses
+
+In v1, some endpoints returned "hydrated" objects — related object details were embedded directly in the response alongside their IDs. For example, a transaction included `category_name`, `asset_name`, and an array of full tag objects.
+
+In v2, responses are **non-hydrated**: related objects are returned as IDs only. To get the full details, call the appropriate endpoint with the returned ID.
+
+```javascript
+// v1 — category details embedded in transaction
+{ "category_id": 456, "category_name": "Groceries", "is_income": false }
+
+// v2 — ID only; fetch separately when needed
+{ "category_id": 456 }
+// GET /v2/categories/456 → { "id": 456, "name": "Groceries", ... }
+```
+
+This improves response times and keeps the API consistent. For apps that need related object details frequently, maintaining a local cache of categories, accounts, and tags is the recommended pattern.
+
+## Updating Objects (PUT)
+
+Most objects in the v2 API are updatable via `PUT /endpoint/{id}`. The rules are consistent:
+
+- Request bodies may contain any mix of **user-definable** properties (will be updated) and **system-defined** properties like `id` or `created_at` (accepted but ignored).
+- Any unexpected property that is neither user-definable nor system-defined will fail validation and return `400`.
+
+> [!WARNING] Overwrite Behavior
+> Complex properties — objects and arrays — are **replaced entirely** by whatever is in the request body. To add a tag to a transaction without removing existing tags, first fetch the transaction, add the new tag ID to the existing `tag_ids` array, then PUT the full updated array.
+
+> [!TIP] Recommended Pattern
+> Because system-defined properties are tolerated in PUT requests, you can safely GET an object, modify the properties you want to change, and PUT the whole thing back without stripping system fields first.
+
+## Versioning
+
+The v2 API uses a modified SEMVER scheme:
+
+- **Major** (always `2`) — a new major version would only be released for breaking changes
+- **Minor** — the number of top-level endpoint groups currently supported (e.g., a version supporting `/me`, `/categories`, and `/transactions` has minor version `3`)
+- **Revision** — the number of non-breaking updates since the last endpoint group was added
+
+The [Version History](/v2/version-history) tracks changes release by release.