docs: add API v4 documentation (#154)

content/en/docs/Concepts/_index.md

@@ -7,7 +7,7 @@ description: >
 ---
 
 {{% pageinfo %}}
-This page will be expanded soon.
+This page will is incomplete and needs to be expanded.
 {{% /pageinfo %}}
 
 Envelope Zero has two core principles. It is a

content/en/docs/Reference/api/_index.md

@@ -13,8 +13,8 @@ The backend has automatically generated API documentation available at `/docs/in
 - Any resource will be available at the endpoints `/{resource}` for the collection and `/{resource}/{id}` for a single resource.
 - Filtering on collection endpoints is implemented with URL parameters (“query strings“)
 - All endpoints support the `OPTIONS` HTTP method to be [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) compliant. Use the `OPTIONS` method to discover available HTTP methods
-- Collections **should** always support the HTTP methods `GET` (read resources) and `POST` (create new resource). This might be different for new API versions that do not support all methods yet, but will always be true for the oldest available API version.
-- Resources **should** support the HTTP methods `GET` (read resource), `PATCH` (update resource) and `DELETE` (delete resource). This might be different for new API versions that do not support all methods yet, but will always be true for the oldest available API version.
+- Collections support the HTTP methods `GET` (read resources) and `POST` (create new resource). **Note**: The newest API version might not yet support all methods for all endpoints. In this case, you can use an older API version if necessary.
+- Resources support the HTTP methods `GET` (read resource), `PATCH` (update resource) and `DELETE` (delete resource). **Note**: The newest API version might not yet support all methods for all endpoints. In this case, you can use an older API version if necessary.
 
 ## Resources
 

content/en/docs/Reference/api/v3/_index.md → content/en/docs/Reference/api/v4/_index.md

@@ -1,20 +1,20 @@
 ---
-title: "v3"
+title: "v4"
 description: >
- This document describes API version 3
+ This document describes API version 4
 ---
 
 ## General
 
-This describes general behavior of all API endpoints
+This describes general behavior of all API endpoints.
 
-- All API responses either have an empty body (only for HTTP 204 responses) or the body consists of only JSON. (unchanged from v1, v2)
-- All attributes for a resource are always contained in the objects that the API returns. (unchanged from v1, v2)
-- The `error` property is either a string or `null`. Each non-204 API response always contains an `error` property (**changed from v1, v2**)
-- The `data` property is either an array of objects for collection endpoints or a single object for resource endpoints. (unchanged from v2)
-- `POST` endpoints take a array of objects to be created. The response will also be a list of objects, where every object has a `data` and an `error` property. If an error ocurred, `error` will contain an error message. If no error occurs, `error` is `null` and `data` contains the created resource. (unchanged from v2)
-- `PATCH` endpoints and `GET` resource endpoints return an object with an `error` and a `data` property. If an error ocurred, the `error` property contains a human readable error message intended for the end user. If no error occurs, `error` is null and `data` contains the resource (**changed from v2**)
-- `GET` collection endpoints return an object with an `error` and a `data` property. If an error ocurred, the `error` property contains a human readable error message intended for the end user. If no error occurs, `error` is null and `data` contains an array of objects where each object is a resource (**changed from v2**)
+- Response bodies (execpt for HTTP 204) are JSON.
+- A repsonse for a resource always contains all attributes
+- The `error` property is either a string or `null`. Each non-204 API response always contains an `error` property.
+- The `data` property is either an array of objects for collection endpoints or a single object for resource endpoints.
+- `POST` endpoints take a array of objects to be created. The response will also be a list of objects, where every object has a `data` and an `error` property. If an error ocurred, `error` will contain an error message. If no error occurs, `error` is `null` and `data` contains the created resource.
+- `PATCH` endpoints and `GET` resource endpoints return an object with an `error` and a `data` property. If an error ocurred, the `error` property contains a human readable error message intended for the end user. If no error occurs, `error` is null and `data` contains the resource
+- `GET` collection endpoints return an object with an `error` and a `data` property. If an error ocurred, the `error` property contains a human readable error message intended for the end user. If no error occurs, `error` is null and `data` contains an array of objects where each object is a resource
 
 ## Modifying resources
 
@@ -33,4 +33,4 @@ for the different resources Envelope Zero knows, e.g. a Transaction.
 
 However, these schemas can be used to validate that the general request or response format is implemented correctly.
 
-{{< directoryindex path="/static/schemas/v3" pathURL="/schemas/v3" >}}
+{{< directoryindex path="/static/schemas/v4" pathURL="/schemas/v4" >}}

content/en/docs/Reference/api/v3/accounts.md → content/en/docs/Reference/api/v4/accounts.md

@@ -1,7 +1,7 @@
 ---
 title: "Accounts"
 description: >
- This document describes Accounts in API version 3
+ This document describes accounts
 ---
 
 ## Recent Envelopes

content/en/docs/Reference/api/v4/changes.md

@@ -0,0 +1,10 @@
+---
+title: "Changes from v3"
+description: >
+ API changes from v3 to v4
+---
+
+- the budget ID is removed from the transaction resource
+- calculated fields have been removed from the `GET /accounts` endpoint, instead, use
+ - `/accounts/{id}/recent-envelopes` for the recently used envelopes
+ - `/accounts/computed` for the accounts' calculated data

content/en/docs/Reference/api/v3/matchRules.md → content/en/docs/Reference/api/v4/matchRules.md

@@ -1,9 +1,9 @@
 ---
 title: "Match Rules"
 description: >
- This document describes Match Rules in API version 3
+ This document describes match rules
 ---
 
 ## Migrating from v2
 
-The `match` filter on GET requests to the collection endpoint is now matching all Match Rules **containing** the string. If it is explicitly set to empty, only Match Rules with an empty match are returned.
+The `match` filter on GET requests to the collection endpoint is now matching all Match Rules **containing** the string. If it is explicitly set to empty, only match rules with an empty match are returned.

content/en/docs/Usage/import/transactions.md

@@ -15,5 +15,4 @@ In the transaction list, use the "Import Transactions" button and follow the ins
 ## Known bugs
 
 - External Accounts are created multiple times if they are referenced multiple times during the same import action: [frontend#1017](https://github.com/envelope-zero/frontend/issues/1017)
-- A CSV file that is empty or only has one line leads to a blank page [frontend#1014](https://github.com/envelope-zero/frontend/issues/1014)
 - Using the "Import" button in quick succession leads to duplicate transactions [frontend#1013](https://github.com/envelope-zero/frontend/issues/1013)