From 28cf67e7ffaf8a72de94920bd1432a215cebacf7 Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Mon, 10 Nov 2025 17:10:59 +0100 Subject: [PATCH] :tada: Add management RPC API (#7700) * :tada: Add management RPC API And refactor internal http auth flow * :paperclip: Adjust final url namings * :books: Update changelog --- CHANGES.md | 6 + backend/dev/user.clj | 1 + backend/resources/app/templates/api-doc.tmpl | 23 ++- .../resources/app/templates/main-api-doc.tmpl | 1 + .../app/templates/management-api-doc.tmpl | 10 + backend/resources/app/templates/openapi.tmpl | 4 +- backend/src/app/auth/oidc.clj | 7 +- backend/src/app/config.clj | 5 +- backend/src/app/http.clj | 15 +- backend/src/app/http/access_token.clj | 74 +++---- backend/src/app/http/errors.clj | 7 +- backend/src/app/http/management.clj | 18 +- backend/src/app/http/middleware.clj | 59 ++++++ backend/src/app/http/session.clj | 93 ++++----- backend/src/app/main.clj | 28 ++- backend/src/app/rpc.clj | 195 +++++++++++++----- backend/src/app/rpc/commands/access_token.clj | 1 + backend/src/app/rpc/doc.clj | 130 +++++++----- .../src/app/rpc/management/subscription.clj | 183 ++++++++++++++++ backend/src/app/util/template.clj | 2 +- .../http_middleware_access_token_test.clj | 57 ----- .../backend_tests/http_middleware_test.clj | 161 +++++++++++++++ backend/test/backend_tests/rpc_doc_test.clj | 2 +- common/src/app/common/uri.cljc | 9 + frontend/playwright/ui/pages/BasePage.js | 2 +- frontend/playwright/ui/specs/example.spec.js | 2 +- frontend/src/app/main/data/event.cljs | 2 +- frontend/src/app/main/repo.cljs | 4 +- frontend/src/app/worker/thumbnails.cljs | 2 +- 29 files changed, 782 insertions(+), 321 deletions(-) create mode 100644 backend/resources/app/templates/main-api-doc.tmpl create mode 100644 backend/resources/app/templates/management-api-doc.tmpl create mode 100644 backend/src/app/rpc/management/subscription.clj delete mode 100644 backend/test/backend_tests/http_middleware_access_token_test.clj create mode 100644 backend/test/backend_tests/http_middleware_test.clj diff --git a/CHANGES.md b/CHANGES.md index 53738d3172..bba07924fa 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,6 +4,12 @@ ### :boom: Breaking changes & Deprecations +- The backend RPC API URLS are changed from `/api/rpc/command/` + to `/api/main/methods/` (the previou PATH is preserved for + backward compatibility; however, if you are a user of this API, it + is strongly recommended that you adapt your code to use the new + PATH. + ### :rocket: Epics and highlights ### :heart: Community contributions (Thank you!) diff --git a/backend/dev/user.clj b/backend/dev/user.clj index 93197eb059..716a0f3c5a 100644 --- a/backend/dev/user.clj +++ b/backend/dev/user.clj @@ -27,6 +27,7 @@ [app.common.transit :as t] [app.common.types.file :as ctf] [app.common.uuid :as uuid] + [app.common.uri :as u] [app.config :as cf] [app.db :as db] [app.main :as main] diff --git a/backend/resources/app/templates/api-doc.tmpl b/backend/resources/app/templates/api-doc.tmpl index 8c67fdeeeb..cf848034a6 100644 --- a/backend/resources/app/templates/api-doc.tmpl +++ b/backend/resources/app/templates/api-doc.tmpl @@ -4,7 +4,7 @@ - Builtin API Documentation - Penpot + {{label|upper}} API Documentation @@ -19,7 +19,7 @@
-

Penpot API Documentation (v{{version}})

+

{{label|upper}}: API Documentation (v{{version}})

[

INTRODUCTION

-

This documentation is intended to be a general overview of the penpot RPC API. - If you prefer, you can use OpenAPI - and/or SwaggerUI as alternative.

+

This documentation is intended to be a general overview of + the {{label}} API. If you prefer, you can + use Swagger/OpenAPI as + alternative.

GENERAL NOTES

@@ -43,7 +44,7 @@ that starts with get- in the name, can use GET HTTP method which in many cases benefits from the HTTP cache.

- + {% block auth-section %}

Authentication

The penpot backend right now offers two way for authenticate the request: cookies (the same mechanism that we use ourselves on accessing the API from the @@ -56,9 +57,10 @@

The access token can be obtained on the appropriate section on profile settings and it should be provided using `Authorization` header with `Token <token-string>` value.

+ {% endblock %}

Content Negotiation

-

The penpot API by default operates indistinctly with: `application/json` +

This API operates indistinctly with: `application/json` and `application/transit+json` content types. You should specify the desired content-type on the `Accept` header, the transit encoding is used by default.

@@ -75,13 +77,16 @@ standard Fetch API

+ {% block limits-section %}

Limits

The rate limit work per user basis (this means that different api keys share the same rate limit). For now the limits are not documented because we are studying and analyzing the data. As a general rule, it should not be abused, if an abusive use is detected, we will proceed to block the user's access to the API.

+ {% endblock %} + {% block webhooks-section %}

Webhooks

All methods that emit webhook events are marked with flag WEBHOOK, the data structure defined on each method represents the payload of the @@ -97,9 +102,11 @@ "profileId": "db601c95-045f-808b-8002-361312e63531" } + {% endblock %} +

-

RPC METHODS REFERENCE:

+

METHODS REFERENCE:

    {% for item in methods %} {% include "app/templates/api-doc-entry.tmpl" with item=item %} diff --git a/backend/resources/app/templates/main-api-doc.tmpl b/backend/resources/app/templates/main-api-doc.tmpl new file mode 100644 index 0000000000..637b82e7a4 --- /dev/null +++ b/backend/resources/app/templates/main-api-doc.tmpl @@ -0,0 +1 @@ +{% extends "app/templates/api-doc.tmpl" %} diff --git a/backend/resources/app/templates/management-api-doc.tmpl b/backend/resources/app/templates/management-api-doc.tmpl new file mode 100644 index 0000000000..629fc427de --- /dev/null +++ b/backend/resources/app/templates/management-api-doc.tmpl @@ -0,0 +1,10 @@ +{% extends "app/templates/api-doc.tmpl" %} + +{% block auth-section %} +{% endblock %} + +{% block limits-section %} +{% endblock %} + +{% block webhooks-section %} +{% endblock %} diff --git a/backend/resources/app/templates/openapi.tmpl b/backend/resources/app/templates/openapi.tmpl index 78e2577f2e..fd31d955a3 100644 --- a/backend/resources/app/templates/openapi.tmpl +++ b/backend/resources/app/templates/openapi.tmpl @@ -7,7 +7,7 @@ name="description" content="SwaggerUI" /> - PENPOT Swagger UI + {{label|upper}} API @@ -16,7 +16,7 @@