Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Added schema to transform API responses (#68256)

Nathan Voxlandeb3d3d806bd3
diff --git a/src/metabase/models/transforms/transform_run.clj b/src/metabase/models/transforms/transform_run.clj
index d4ba5c03ef5..b5c0415814a 100644
--- a/src/metabase/models/transforms/transform_run.clj
+++ b/src/metabase/models/transforms/transform_run.clj
@@ -298,6 +298,7 @@
join-clause (paged-runs-join-clause params)
count-options (m/assoc-some {} :where where-clause)
query-options (m/assoc-some {:order-by order-by :offset offset :limit limit}
+ :select (when join-clause [:transform_run.*])
:where where-clause
:left-join join-clause)
runs (t2/select :model/TransformRun query-options)
diff --git a/src/metabase/transforms/api/transform.clj b/src/metabase/transforms/api/transform.clj
index 52e654b007d..ebfd39aa248 100644
--- a/src/metabase/transforms/api/transform.clj
+++ b/src/metabase/transforms/api/transform.clj
@@ -51,6 +51,90 @@
(mr/def ::run-trigger
[:enum "none" "global-schedule"])
+(def ^:private CreatorResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:email :string]
+ [:first_name [:maybe :string]]
+ [:last_name [:maybe :string]]
+ [:common_name {:optional true} [:maybe :string]]
+ [:last_login {:optional true} [:maybe :any]]
+ [:is_qbnewb {:optional true} :boolean]
+ [:is_superuser {:optional true} :boolean]
+ [:is_data_analyst {:optional true} :boolean]
+ [:tenant_id {:optional true} [:maybe :any]]
+ [:date_joined {:optional true} :any]])
+
+(def ^:private OwnerResponse
+ [:map {:closed true}
+ [:id {:optional true} pos-int?]
+ [:email :string]
+ [:first_name {:optional true} [:maybe :string]]
+ [:last_name {:optional true} [:maybe :string]]
+ [:common_name {:optional true} [:maybe :string]]])
+
+(def ^:private TransformLastRunResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:transform_id pos-int?]
+ [:run_method :keyword]
+ [:status [:enum :started :succeeded :failed :timeout :canceled :canceling]]
+ [:is_active [:maybe :boolean]]
+ [:start_time :any]
+ [:end_time {:optional true} [:maybe :any]]
+ [:message [:maybe :string]]
+ [:user_id [:maybe pos-int?]]
+ [:transform_name {:optional true} [:maybe :string]]
+ [:transform_entity_id {:optional true} [:maybe :string]]])
+
+(def ^:private TransformResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:name :string]
+ [:description [:maybe :string]]
+ [:source :any]
+ [:target :any]
+ [:source_type :keyword]
+ [:source_database_id {:optional true} [:maybe pos-int?]]
+ [:source_readable {:optional true} :boolean]
+ [:entity_id [:maybe :string]]
+ [:created_at :any]
+ [:updated_at :any]
+ [:creator_id pos-int?]
+ [:collection_id [:maybe pos-int?]]
+ [:target_db_id {:optional true} [:maybe pos-int?]]
+ [:run_trigger {:optional true} [:maybe :keyword]]
+ [:dependency_analysis_version :int]
+ [:creator CreatorResponse]
+ [:last_run {:optional true} [:maybe TransformLastRunResponse]]
+ [:tag_ids {:optional true} [:sequential pos-int?]]
+ [:table {:optional true} [:maybe :map]]
+ [:owner_user_id {:optional true} [:maybe pos-int?]]
+ [:owner_email {:optional true} [:maybe :string]]
+ [:owner {:optional true} [:maybe OwnerResponse]]])
+
+(def ^:private TransformRunResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:transform_id [:maybe pos-int?]]
+ [:run_method :keyword]
+ [:status [:enum :started :succeeded :failed :timeout :canceled :canceling]]
+ [:is_active [:maybe :boolean]]
+ [:start_time :any]
+ [:end_time {:optional true} [:maybe :any]]
+ [:message [:maybe :string]]
+ [:user_id [:maybe pos-int?]]
+ [:transform_name {:optional true} [:maybe :string]]
+ [:transform_entity_id {:optional true} [:maybe :string]]
+ ;; Transform can have id/name when exists, or be nil when deleted
+ [:transform {:optional true} [:maybe [:map {:closed true}
+ [:id {:optional true} pos-int?]
+ [:name {:optional true} :string]
+ [:deleted {:optional true} :boolean]
+ [:collection_id {:optional true} [:maybe pos-int?]]
+ [:collection {:optional true} [:maybe :map]]
+ [:tag_ids {:optional true} [:sequential pos-int?]]]]]])
+
(defn- python-source-table-ref->table-id
"Change source of python transform from name->table-ref to name->table-id.
@@ -113,13 +197,8 @@
;; TODO (Cam 10/28/25) -- fix this endpoint so it uses kebab-case for query parameters for consistency with the rest
;; of the REST API
-;;
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case
- :metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/"
+#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case]}
+(api.macros/defendpoint :get "/" :- [:sequential TransformResponse]
"Get a list of transforms."
[_route-params
query-params :-
@@ -236,8 +315,7 @@
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/"
+(api.macros/defendpoint :post "/" :- TransformResponse
"Create a new transform."
[_route-params
_query-params
@@ -275,21 +353,13 @@
python-source-table-ref->table-id
transforms.util/add-source-readable)))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/:id"
+(api.macros/defendpoint :get "/:id" :- TransformResponse
"Get a specific transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
(get-transform id))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/:id/dependencies"
+(api.macros/defendpoint :get "/:id/dependencies" :- [:sequential TransformResponse]
"Get the dependencies of a specific transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
@@ -332,13 +402,12 @@
;; TODO (Cam 10/28/25) -- fix this endpoint so it uses kebab-case for query parameters for consistency with the rest
;; of the REST API
-;;
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case
- :metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/run"
+#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case]}
+(api.macros/defendpoint :get "/run" :- [:map {:closed true}
+ [:data [:sequential TransformRunResponse]]
+ [:limit pos-int?]
+ [:offset :int]
+ [:total :int]]
"Get transform runs based on a set of filter params."
[_route-params
query-params :-
@@ -390,11 +459,7 @@
python-source-table-ref->table-id
transforms.util/add-source-readable)))
-;; TODO (Cam 2025-11-25) -- please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :put "/:id"
+(api.macros/defendpoint :put "/:id" :- TransformResponse
"Update a transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]
@@ -421,21 +486,13 @@
:user-id api/*current-user-id*})
nil)
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :delete "/:id"
+(api.macros/defendpoint :delete "/:id" :- :nil
"Delete a transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
(delete-transform! (api/write-check :model/Transform id)))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :delete "/:id/table"
+(api.macros/defendpoint :delete "/:id/table" :- :nil
"Delete a transform's output table."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
@@ -443,11 +500,7 @@
(transforms.util/delete-target-table-by-id! id)
nil)
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/:id/cancel"
+(api.macros/defendpoint :post "/:id/cancel" :- :nil
"Cancel the current run for a given transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
@@ -477,11 +530,11 @@
:run_id run-id})
(assoc :status 202)))))
-;; TODO (Cam 2025-11-25) -- please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/:id/run"
+(api.macros/defendpoint :post "/:id/run" :- [:map
+ [:status [:= 202]]
+ [:body [:map {:closed true}
+ [:message :any]
+ [:run_id [:maybe pos-int?]]]]]
"Run a transform."
[{:keys [id]} :- [:map
[:id ms/PositiveInt]]]
@@ -519,11 +572,9 @@
(log/debugf e "Failed to parse query: %s" (ex-message e))
{:is_simple false})))
-;; TODO (Cam 2025-12-04) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/is-simple-query"
+(api.macros/defendpoint :post "/is-simple-query" :- [:map
+ [:is_simple :boolean]
+ [:reason {:optional true} :string]]
"Checks if a native SQL query string is simple enough for automatic checkpoint insertion"
[_route-params
_query-params
diff --git a/src/metabase/transforms/api/transform_job.clj b/src/metabase/transforms/api/transform_job.clj
index e8bb19ce82b..2adaad96988 100644
--- a/src/metabase/transforms/api/transform_job.clj
+++ b/src/metabase/transforms/api/transform_job.clj
@@ -9,7 +9,7 @@
[metabase.transforms.jobs :as transforms.jobs]
[metabase.transforms.schedule :as transforms.schedule]
[metabase.transforms.util :as transforms.util]
- [metabase.util.i18n :refer [deferred-tru]]
+ [metabase.util.i18n :refer [deferred-tru LocalizedString]]
[metabase.util.jvm :as u.jvm]
[metabase.util.log :as log]
[metabase.util.malli.schema :as ms]
@@ -21,11 +21,71 @@
(def ^:private ui-display-types [:cron/raw :cron/builder])
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/"
+(def ^:private LastRunResponse
+ "Schema for a job's last run information."
+ [:map {:closed true}
+ [:id pos-int?]
+ [:job_id pos-int?]
+ [:run_method :keyword]
+ [:status [:enum :started :succeeded :failed :timeout]]
+ [:is_active [:maybe :boolean]]
+ [:start_time :any]
+ [:end_time {:optional true} [:maybe :any]]
+ [:message [:maybe :string]]
+ [:created_at :any]
+ [:updated_at :any]])
+
+(def ^:private NextRunResponse
+ [:map {:closed true}
+ [:start_time :any]])
+
+(def ^:private TransformJobResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:name [:or :string LocalizedString]]
+ [:description [:maybe [:or :string LocalizedString]]]
+ [:schedule :string]
+ [:ui_display_type [:enum :cron/raw :cron/builder]]
+ [:entity_id [:maybe :string]]
+ [:created_at :any]
+ [:updated_at :any]
+ [:built_in_type {:optional true} [:maybe :string]]
+ [:tag_ids {:optional true} [:sequential pos-int?]]
+ [:last_run {:optional true} [:maybe LastRunResponse]]
+ [:next_run {:optional true} [:maybe NextRunResponse]]])
+
+(def ^:private CreatorResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:email :string]
+ [:date_joined {:optional true} :any]
+ [:first_name [:maybe :string]]
+ [:last_name [:maybe :string]]
+ [:last_login {:optional true} [:maybe :any]]
+ [:is_superuser {:optional true} :boolean]
+ [:is_qbnewb {:optional true} :boolean]
+ [:is_data_analyst {:optional true} :boolean]
+ [:tenant_id {:optional true} [:maybe :string]]
+ [:common_name {:optional true} [:maybe :string]]])
+
+(def ^:private TransformResponse
+ [:map
+ [:id pos-int?]
+ [:name :string]
+ [:description [:maybe :string]]
+ [:source :any]
+ [:target :any]
+ [:source_type :keyword]
+ [:entity_id [:maybe :string]]
+ [:created_at :any]
+ [:updated_at :any]
+ [:creator_id pos-int?]
+ [:collection_id [:maybe pos-int?]]
+ [:run_trigger {:optional true} [:maybe :keyword]]
+ [:dependency_analysis_version :int]
+ [:creator CreatorResponse]])
+
+(api.macros/defendpoint :post "/" :- TransformJobResponse
"Create a new transform job."
[_route-params
_query-params
@@ -65,11 +125,7 @@
;; Return with hydrated tag_ids
(t2/hydrate job :tag_ids)))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :put "/:job-id"
+(api.macros/defendpoint :put "/:job-id" :- TransformJobResponse
"Update a transform job."
[{:keys [job-id]} :- [:map
[:job-id ms/PositiveInt]]
@@ -114,11 +170,7 @@
(-> (t2/select-one :model/TransformJob :id job-id)
(t2/hydrate :tag_ids :last_run))))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :delete "/:job-id"
+(api.macros/defendpoint :delete "/:job-id" :- nil
"Delete a transform job."
[{:keys [job-id]} :- [:map [:job-id ms/PositiveInt]]]
(log/info "Deleting transform job" job-id)
@@ -127,11 +179,9 @@
(transforms.schedule/delete-job! job-id)
api/generic-204-no-content)
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/:job-id/run"
+(api.macros/defendpoint :post "/:job-id/run" :- [:map {:closed true}
+ [:message :string]
+ [:job_run_id :string]]
"Run a transform job manually."
[{:keys [job-id]} :- [:map [:job-id ms/PositiveInt]]]
(log/info "Manual run of transform job" job-id)
@@ -146,11 +196,7 @@
{:message "Job run started"
:job_run_id (str "stub-" job-id "-" (System/currentTimeMillis))})
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/:job-id"
+(api.macros/defendpoint :get "/:job-id" :- TransformJobResponse
"Get a transform job by ID."
[{:keys [job-id]} :- [:map
[:job-id ms/PositiveInt]]]
@@ -164,11 +210,7 @@
(assoc job :next_run {:start_time (str (transforms.util/->instant start-time))})
job))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/:job-id/transforms"
+(api.macros/defendpoint :get "/:job-id/transforms" :- [:sequential TransformResponse]
"Get the transforms of job specified by the job's ID."
[{:keys [job-id]} :- [:map
[:job-id ms/PositiveInt]]]
@@ -181,13 +223,8 @@
;; TODO (Cam 10/28/25) -- fix this endpoint so it uses kebab-case for query parameters for consistency with the rest
;; of the REST API
-;;
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case
- :metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/"
+#_{:clj-kondo/ignore [:metabase/validate-defendpoint-query-params-use-kebab-case]}
+(api.macros/defendpoint :get "/" :- [:sequential TransformJobResponse]
"Get all transform jobs."
[_route-params
{:keys [last_run_start_time next_run_start_time last_run_statuses tag_ids]} :-
diff --git a/src/metabase/transforms/api/transform_tag.clj b/src/metabase/transforms/api/transform_tag.clj
index 36b2729c381..ffa7e24752c 100644
--- a/src/metabase/transforms/api/transform_tag.clj
+++ b/src/metabase/transforms/api/transform_tag.clj
@@ -5,18 +5,24 @@
[metabase.api.routes.common :refer [+auth]]
[metabase.models.interface :as mi]
[metabase.models.transforms.transform-tag :as transform-tag]
- [metabase.util.i18n :refer [deferred-tru]]
+ [metabase.util.i18n :refer [deferred-tru LocalizedString]]
[metabase.util.log :as log]
[metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
(set! *warn-on-reflection* true)
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/"
+(def ^:private TransformTagResponse
+ [:map {:closed true}
+ [:id pos-int?]
+ [:name [:or :string LocalizedString]]
+ [:entity_id [:maybe :string]]
+ [:created_at :any]
+ [:updated_at :any]
+ [:built_in_type {:optional true} [:maybe :string]]
+ [:can_run {:optional true} :boolean]])
+
+(api.macros/defendpoint :post "/" :- TransformTagResponse
"Create a new transform tag."
[_route-params
_query-params
@@ -28,11 +34,7 @@
(deferred-tru "A tag with the name ''{0}'' already exists." name))
(t2/insert-returning-instance! :model/TransformTag {:name name}))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :put "/:tag-id"
+(api.macros/defendpoint :put "/:tag-id" :- TransformTagResponse
"Update a transform tag."
[{:keys [tag-id]} :- [:map
[:tag-id ms/PositiveInt]]
@@ -46,24 +48,16 @@
(t2/update! :model/TransformTag tag-id {:name name})
(t2/select-one :model/TransformTag :id tag-id))
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :delete "/:tag-id"
+(api.macros/defendpoint :delete "/:tag-id" :- :nil
"Delete a transform tag. Removes it from all transforms and jobs."
[{:keys [tag-id]} :- [:map
[:tag-id ms/PositiveInt]]]
(log/info "Deleting transform tag" tag-id)
(api/write-check (t2/select-one :model/TransformTag :id tag-id))
(t2/delete! :model/TransformTag :id tag-id)
- api/generic-204-no-content)
+ nil)
-;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
-;; use our API + we will need it when we make auto-TypeScript-signature generation happen
-;;
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :get "/"
+(api.macros/defendpoint :get "/" :- [:sequential TransformTagResponse]
"Get a list of all transform tags."
[_route-params
_query-params]