From 28222daf94ae06a070f1e3eac384c27b2d9aed3b Mon Sep 17 00:00:00 2001 From: morre Date: Sun, 1 Sep 2024 22:21:34 +0200 Subject: [PATCH] docs: add API v4 documentation (#154) --- content/en/docs/Concepts/_index.md | 2 +- content/en/docs/Reference/api/_index.md | 4 +-- content/en/docs/Reference/api/v1.md | 15 --------- content/en/docs/Reference/api/v2/_index.md | 33 ------------------- content/en/docs/Reference/api/v2/accounts.md | 19 ----------- .../docs/Reference/api/{v3 => v4}/_index.md | 22 ++++++------- .../docs/Reference/api/{v3 => v4}/accounts.md | 2 +- content/en/docs/Reference/api/v4/changes.md | 10 ++++++ .../Reference/api/{v3 => v4}/matchRules.md | 4 +-- content/en/docs/Usage/import/transactions.md | 1 - static/schemas/{v3 => v4}/error.schema.json | 0 .../get-collection.response.schema.json | 0 .../get-patch-resource.response.schema.json | 0 .../{v3 => v4}/options.response.schema.json | 0 .../schemas/{v3 => v4}/pagination.schema.json | 0 .../{v3 => v4}/patch.request.schema.json | 0 .../{v3 => v4}/post.request.schema.json | 0 .../{v3 => v4}/post.response.schema.json | 0 18 files changed, 27 insertions(+), 85 deletions(-) delete mode 100644 content/en/docs/Reference/api/v1.md delete mode 100644 content/en/docs/Reference/api/v2/_index.md delete mode 100644 content/en/docs/Reference/api/v2/accounts.md rename content/en/docs/Reference/api/{v3 => v4}/_index.md (69%) rename content/en/docs/Reference/api/{v3 => v4}/accounts.md (92%) create mode 100644 content/en/docs/Reference/api/v4/changes.md rename content/en/docs/Reference/api/{v3 => v4}/matchRules.md (63%) rename static/schemas/{v3 => v4}/error.schema.json (100%) rename static/schemas/{v3 => v4}/get-collection.response.schema.json (100%) rename static/schemas/{v3 => v4}/get-patch-resource.response.schema.json (100%) rename static/schemas/{v3 => v4}/options.response.schema.json (100%) rename static/schemas/{v3 => v4}/pagination.schema.json (100%) rename static/schemas/{v3 => v4}/patch.request.schema.json (100%) rename static/schemas/{v3 => v4}/post.request.schema.json (100%) rename static/schemas/{v3 => v4}/post.response.schema.json (100%) diff --git a/content/en/docs/Concepts/_index.md b/content/en/docs/Concepts/_index.md index ddcbd63..96c560f 100644 --- a/content/en/docs/Concepts/_index.md +++ b/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 diff --git a/content/en/docs/Reference/api/_index.md b/content/en/docs/Reference/api/_index.md index ebd3bde..3971316 100644 --- a/content/en/docs/Reference/api/_index.md +++ b/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 diff --git a/content/en/docs/Reference/api/v1.md b/content/en/docs/Reference/api/v1.md deleted file mode 100644 index 677dea2..0000000 --- a/content/en/docs/Reference/api/v1.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "v1" -description: > - This document describes API version 1 ---- - -## General - -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. -- The `error` key always has a value of type `string`, containing a human readable error message. Those error messages are intended to be passed to the user of the application. -- All attributes for a resource are always contained in the objects that the API returns. -- All API responses have **either** a `data` or an `error` top level key. They can’t appear at the same time. -- The `data` key is either a list of objects (for collection endpoints) or a single object (for resource endpoints). diff --git a/content/en/docs/Reference/api/v2/_index.md b/content/en/docs/Reference/api/v2/_index.md deleted file mode 100644 index a185311..0000000 --- a/content/en/docs/Reference/api/v2/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "v2" -description: > - This document describes API version 2 ---- - -{{% pageinfo %}} -API v2 does not yet have endpoints for all resources. As long as new endpoints are added, this document will be updated with them. -{{% /pageinfo %}} - -## General - -This describes general behavior of all API endpoints - -### Unchanged from v1 - -- All API responses either have an empty body (only for HTTP 204 responses) or the body consists of only JSON. -- The `error` key always has a value of type `string`, containing a human readable error message. Those error messages are intended to be passed to the user of the application. -- API responses always contain all attributes for an object - -### Changed in v2 - -- API responses do not all have a `data` or `error` key on the top level. Unsuccessful requests will have a response with an `error` key (this is unchanged to v1). Successful API responses will behave as described below. -- API responses are either a list of objects (for collection endpoints) or a single object (for resource endpoints). -- `POST` endpoints now take a **list** of objects to be created, not a singular object. The response will also be a list of objects, where every object has a `data` and an `error` key. 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 the resource object (instead of a map containing a key `data` with the resource object as value) -- `GET` list endpoints return a list of the resource objects (instead of a map containing a key `data` with a list of the resource objects as value) - -## Migrating from v1 - -_Changes to all endpoints are covered in [Changed in v2](#changed-in-v2)._ - -For changes to the different resources, check their respective pages. diff --git a/content/en/docs/Reference/api/v2/accounts.md b/content/en/docs/Reference/api/v2/accounts.md deleted file mode 100644 index bd6ff3e..0000000 --- a/content/en/docs/Reference/api/v2/accounts.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Accounts" -description: > - This document describes Accounts in API version 2 ---- - -## Recent Envelopes - -The `recentEnvelopes` field is a list of the 5 most common Envelopes that were used for the last 50 transactions where the account was the destination. -The list is ordered by the frequency with the most common Envelope being the first one. If two Envelopes have been used the same amount of times, -the one that was created **more recently** is first in the list. - -Income transactions are also counted in this list, with income appearing as the `null` value. - -Use this field to pre-fill the Envelope when creating transactions in a client. - -## Migrating from v1 - -- The `recentEnvelopes` field is now a list of IDs instead of a list envelope objects. Income is represented by `null` diff --git a/content/en/docs/Reference/api/v3/_index.md b/content/en/docs/Reference/api/v4/_index.md similarity index 69% rename from content/en/docs/Reference/api/v3/_index.md rename to content/en/docs/Reference/api/v4/_index.md index 6cfcb93..e891323 100644 --- a/content/en/docs/Reference/api/v3/_index.md +++ b/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" >}} diff --git a/content/en/docs/Reference/api/v3/accounts.md b/content/en/docs/Reference/api/v4/accounts.md similarity index 92% rename from content/en/docs/Reference/api/v3/accounts.md rename to content/en/docs/Reference/api/v4/accounts.md index f169731..c705fb8 100644 --- a/content/en/docs/Reference/api/v3/accounts.md +++ b/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 diff --git a/content/en/docs/Reference/api/v4/changes.md b/content/en/docs/Reference/api/v4/changes.md new file mode 100644 index 0000000..1013862 --- /dev/null +++ b/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 diff --git a/content/en/docs/Reference/api/v3/matchRules.md b/content/en/docs/Reference/api/v4/matchRules.md similarity index 63% rename from content/en/docs/Reference/api/v3/matchRules.md rename to content/en/docs/Reference/api/v4/matchRules.md index 56e5369..e3e11cb 100644 --- a/content/en/docs/Reference/api/v3/matchRules.md +++ b/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. diff --git a/content/en/docs/Usage/import/transactions.md b/content/en/docs/Usage/import/transactions.md index 4bacfb0..e2da692 100644 --- a/content/en/docs/Usage/import/transactions.md +++ b/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) diff --git a/static/schemas/v3/error.schema.json b/static/schemas/v4/error.schema.json similarity index 100% rename from static/schemas/v3/error.schema.json rename to static/schemas/v4/error.schema.json diff --git a/static/schemas/v3/get-collection.response.schema.json b/static/schemas/v4/get-collection.response.schema.json similarity index 100% rename from static/schemas/v3/get-collection.response.schema.json rename to static/schemas/v4/get-collection.response.schema.json diff --git a/static/schemas/v3/get-patch-resource.response.schema.json b/static/schemas/v4/get-patch-resource.response.schema.json similarity index 100% rename from static/schemas/v3/get-patch-resource.response.schema.json rename to static/schemas/v4/get-patch-resource.response.schema.json diff --git a/static/schemas/v3/options.response.schema.json b/static/schemas/v4/options.response.schema.json similarity index 100% rename from static/schemas/v3/options.response.schema.json rename to static/schemas/v4/options.response.schema.json diff --git a/static/schemas/v3/pagination.schema.json b/static/schemas/v4/pagination.schema.json similarity index 100% rename from static/schemas/v3/pagination.schema.json rename to static/schemas/v4/pagination.schema.json diff --git a/static/schemas/v3/patch.request.schema.json b/static/schemas/v4/patch.request.schema.json similarity index 100% rename from static/schemas/v3/patch.request.schema.json rename to static/schemas/v4/patch.request.schema.json diff --git a/static/schemas/v3/post.request.schema.json b/static/schemas/v4/post.request.schema.json similarity index 100% rename from static/schemas/v3/post.request.schema.json rename to static/schemas/v4/post.request.schema.json diff --git a/static/schemas/v3/post.response.schema.json b/static/schemas/v4/post.response.schema.json similarity index 100% rename from static/schemas/v3/post.response.schema.json rename to static/schemas/v4/post.response.schema.json