From b10fef48c0f7647988354e9d3e388d4bcb26463c Mon Sep 17 00:00:00 2001 From: morre Date: Sun, 8 Oct 2023 13:10:30 +0200 Subject: [PATCH] docs: more API v2 descriptions (#45) This adds descriptions for more API v2 endpoints and improves the existing description. --- content/en/docs/Reference/api/v2.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/en/docs/Reference/api/v2.md b/content/en/docs/Reference/api/v2.md index 6757ded..34a66d8 100644 --- a/content/en/docs/Reference/api/v2.md +++ b/content/en/docs/Reference/api/v2.md @@ -16,12 +16,15 @@ 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. +- 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). -- On `POST` endpoints, each object (in the list, if it's a bulk creation endpoint) always 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. +- `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