From f9e3871bb32873a172a5e63055db3ece3eb2acab Mon Sep 17 00:00:00 2001 From: Stefan Benz <46600784+stebenz@users.noreply.github.com> Date: Thu, 4 Dec 2025 08:07:07 +0100 Subject: [PATCH] docs: add rest paths to api design (#9910) # Which Problems Are Solved REST paths for new APIs are unclear as they are not defined in the API_DESIGN. # How the Problems Are Solved Add a part to the API_DESIGN, which can be removed at a later date when migrating to RPC connect. # Additional Changes None # Additional Context None --- API_DESIGN.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/API_DESIGN.md b/API_DESIGN.md index cc89d1c6c..90bb3ef4f 100644 --- a/API_DESIGN.md +++ b/API_DESIGN.md @@ -270,6 +270,30 @@ Additionally, state changes, specific actions or operations that do not fit into - `Send` for sending a resource. - etc. +#### REST Path + +Paths of operations MUST be structured as follows: + +| Operation | Method | Path | +|---------------|--------|------------------------------------------| +| Create/Add | POST | /\/\ | +| Update | POST | /\/\/\ | +| Delete/Remove | DELETE | /\/\/\ | +| Set | PUT | /\/\ | +| Get | GET | /\/\/\ | +| List | POST | /\/\/search | + +Which results in an example path for operations like `/v2beta/users/search`. + +Paths of status changes on resources MUST be structured as follows: + +| Operation | Method | Path | +|------------|--------|-----------------------------------------------------| +| Activate | POST | /\/\/\/activate | +| Deactivate | POST | /\/\/\/deactivate | + +Which results in an example path for status changes like `/v2beta/users/1234567890/activate`. + ## Authentication and Authorization The API uses OAuth 2 for authorization. There are corresponding middlewares that check the access token for validity and