Skip to content
Snippets Groups Projects
Unverified Commit bd53aed6 authored by Jeff Bruemmer's avatar Jeff Bruemmer Committed by GitHub
Browse files

docs - update API docs format (#17716) 


* update API docs format

* account for other terminal punctuation

* clarify api namespace target

* update schema test, add-period test

* update period test

* parens

* test endpoint-section

* cleanup

* Cam edits

Co-authored-by: default avatarCam Saul <1455846+camsaul@users.noreply.github.com>

* trim whitespace

* file newlines

* Sort namespaces

Co-authored-by: default avatarCam Saul <1455846+camsaul@users.noreply.github.com>
Co-authored-by: default avatarCam Saul <github@camsaul.com>
parent 99e9e330
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 914 additions and 523 deletions
docs/api-documentation.md
+ 744
− 505
View file @ bd53aed6
......@@ -2,46 +2,70 @@
_This file was generated from source comments by `clojure -M:run api-documentation`_.
Check out an introduction to the [Metabase API](https://www.metabase.com/learn/developing-applications/advanced-metabase/metabase-api.html).
Check out an introduction to the [Metabase API](https://www.metabase.com/learn/administration/metabase-api.html).
## `GET /api/activity/`
Get recent activity.
## Activity
- [GET /api/activity/](#get-apiactivity)
- [GET /api/activity/recent_views](#get-apiactivityrecentviews)
### `GET /api/activity/`
## `GET /api/activity/recent_views`
Get recent activity.
### `GET /api/activity/recent_views`
Get the list of 10 things the current user has been viewing most recently.
## `DELETE /api/alert/:id`
## Alert
/api/alert endpoints.
Delete an Alert. (DEPRECATED -- don't delete a Alert anymore -- archive it instead.)
- [DELETE /api/alert/:id](#delete-apialertid)
- [GET /api/alert/](#get-apialert)
- [GET /api/alert/:id](#get-apialertid)
- [GET /api/alert/question/:id](#get-apialertquestionid)
- [POST /api/alert/](#post-apialert)
- [PUT /api/alert/:id](#put-apialertid)
- [PUT /api/alert/:id/unsubscribe](#put-apialertidunsubscribe)
### `DELETE /api/alert/:id`
Delete an Alert. (DEPRECATED -- don't delete a Alert anymore -- archive it instead.).
##### PARAMS:
* **`id`**
### `GET /api/alert/`
## `GET /api/alert/`
Fetch all alerts
Fetch all alerts.
##### PARAMS:
* **`archived`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
* **`user_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `GET /api/alert/question/:id`
### `GET /api/alert/:id`
Fetch all questions for the given question (`Card`) id
Fetch an alert by ID.
##### PARAMS:
* **`id`**
### `GET /api/alert/question/:id`
Fetch all questions for the given question (`Card`) id.
##### PARAMS:
* **`id`**
## `POST /api/alert/`
### `POST /api/alert/`
Create a new Alert.
......@@ -59,8 +83,7 @@ Create a new Alert.
* **`new-alert-request-body`**
## `PUT /api/alert/:id`
### `PUT /api/alert/:id`
Update a `Alert` with ID.
......@@ -82,17 +105,28 @@ Update a `Alert` with ID.
* **`alert-updates`**
### `PUT /api/alert/:id/unsubscribe`
## `PUT /api/alert/:id/unsubscribe`
Unsubscribes a user from the given alert
Unsubscribes a user from the given alert.
##### PARAMS:
* **`id`**
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query`
## Automagic dashboards
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query](#get-apiautomagic-dashboardsentityentity-id-or-query)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query](#get-apiautomagic-dashboardsentityentity-id-or-querycellcell-query)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/compare/:comparison-entity/:comparison-entity-id-or-query](#get-apiautomagic-dashboardsentityentity-id-or-querycellcell-querycomparecomparison-entitycomparison-entity-id-or-query)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule](#get-apiautomagic-dashboardsentityentity-id-or-querycellcell-queryruleprefixrule)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query](#get-apiautomagic-dashboardsentityentity-id-or-querycellcell-queryruleprefixrulecomparecomparison-entitycomparison-entity-id-or-query)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/compare/:comparison-entity/:comparison-entity-id-or-query](#get-apiautomagic-dashboardsentityentity-id-or-querycomparecomparison-entitycomparison-entity-id-or-query)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule](#get-apiautomagic-dashboardsentityentity-id-or-queryruleprefixrule)
- [GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query](#get-apiautomagic-dashboardsentityentity-id-or-queryruleprefixrulecomparecomparison-entitycomparison-entity-id-or-query)
- [GET /api/automagic-dashboards/database/:id/candidates](#get-apiautomagic-dashboardsdatabaseidcandidates)
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query`
Return an automagic dashboard for entity `entity` with id `ìd`.
......@@ -104,8 +138,7 @@ Return an automagic dashboard for entity `entity` with id `ìd`.
* **`show`** invalid show value
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query`
Return an automagic dashboard analyzing cell in automagic dashboard for entity `entity`
defined by
......@@ -121,8 +154,7 @@ Return an automagic dashboard analyzing cell in automagic dashboard for entity
* **`show`** invalid show value
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/compare/:comparison-entity/:comparison-entity-id-or-query`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/compare/:comparison-entity/:comparison-entity-id-or-query`
Return an automagic comparison dashboard for cell in automagic dashboard for entity `entity`
with id `ìd` defined by query `cell-querry`; compared with entity `comparison-entity` with id
......@@ -142,8 +174,7 @@ Return an automagic comparison dashboard for cell in automagic dashboard for ent
* **`comparison-entity-id-or-query`**
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule`
Return an automagic dashboard analyzing cell in question with id `id` defined by
query `cell-querry` using rule `rule`.
......@@ -162,8 +193,7 @@ Return an automagic dashboard analyzing cell in question with id `id` defined b
* **`show`** invalid show value
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/cell/:cell-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query`
Return an automagic comparison dashboard for cell in automagic dashboard for entity `entity`
with id `ìd` defined by query `cell-querry` using rule `rule`; compared with entity
......@@ -187,11 +217,10 @@ Return an automagic comparison dashboard for cell in automagic dashboard for ent
* **`comparison-entity-id-or-query`**
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/compare/:comparison-entity/:comparison-entity-id-or-query`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/compare/:comparison-entity/:comparison-entity-id-or-query`
Return an automagic comparison dashboard for entity `entity` with id `ìd` compared with entity
`comparison-entity` with id `comparison-entity-id-or-query.`
`comparison-entity` with id `comparison-entity-id-or-query.`.
##### PARAMS:
......@@ -205,8 +234,7 @@ Return an automagic comparison dashboard for entity `entity` with id `ìd` compa
* **`comparison-entity-id-or-query`**
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule`
Return an automagic dashboard for entity `entity` with id `ìd` using rule `rule`.
......@@ -222,8 +250,7 @@ Return an automagic dashboard for entity `entity` with id `ìd` using rule `rule
* **`show`** invalid show value
## `GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query`
### `GET /api/automagic-dashboards/:entity/:entity-id-or-query/rule/:prefix/:rule/compare/:comparison-entity/:comparison-entity-id-or-query`
Return an automagic comparison dashboard for entity `entity` with id `ìd` using rule `rule`;
compared with entity `comparison-entity` with id `comparison-entity-id-or-query.`.
......@@ -244,8 +271,7 @@ Return an automagic comparison dashboard for entity `entity` with id `ìd` using
* **`comparison-entity-id-or-query`**
## `GET /api/automagic-dashboards/database/:id/candidates`
### `GET /api/automagic-dashboards/database/:id/candidates`
Return a list of candidates for automagic dashboards orderd by interestingness.
......@@ -254,7 +280,29 @@ Return a list of candidates for automagic dashboards orderd by interestingness.
* **`id`**
## `DELETE /api/card/:card-id/favorite`
## Card
/api/card endpoints.
- [DELETE /api/card/:card-id/favorite](#delete-apicardcard-idfavorite)
- [DELETE /api/card/:card-id/public_link](#delete-apicardcard-idpubliclink)
- [DELETE /api/card/:id](#delete-apicardid)
- [GET /api/card/](#get-apicard)
- [GET /api/card/:id](#get-apicardid)
- [GET /api/card/:id/related](#get-apicardidrelated)
- [GET /api/card/embeddable](#get-apicardembeddable)
- [GET /api/card/public](#get-apicardpublic)
- [POST /api/card/](#post-apicard)
- [POST /api/card/:card-id/favorite](#post-apicardcard-idfavorite)
- [POST /api/card/:card-id/public_link](#post-apicardcard-idpubliclink)
- [POST /api/card/:card-id/query](#post-apicardcard-idquery)
- [POST /api/card/:card-id/query/:export-format](#post-apicardcard-idqueryexport-format)
- [POST /api/card/collections](#post-apicardcollections)
- [POST /api/card/pivot/:card-id/query](#post-apicardpivotcard-idquery)
- [POST /api/card/related](#post-apicardrelated)
- [PUT /api/card/:id](#put-apicardid)
### `DELETE /api/card/:card-id/favorite`
Unfavorite a Card.
......@@ -262,8 +310,7 @@ Unfavorite a Card.
* **`card-id`**
## `DELETE /api/card/:card-id/public_link`
### `DELETE /api/card/:card-id/public_link`
Delete the publicly-accessible link to this Card.
......@@ -273,21 +320,19 @@ You must be a superuser to do this.
* **`card-id`**
### `DELETE /api/card/:id`
## `DELETE /api/card/:id`
Delete a Card. (DEPRECATED -- don't delete a Card anymore -- archive it instead.)
Delete a Card. (DEPRECATED -- don't delete a Card anymore -- archive it instead.).
##### PARAMS:
* **`id`**
## `GET /api/card/`
### `GET /api/card/`
Get all the Cards. Option filter param `f` can be used to change the set of Cards that are returned; default is
`all`, but other options include `mine`, `fav`, `database`, `table`, `recent`, `popular`, and `archived`. See
corresponding implementation functions above for the specific behavior of each filter option. :card_index:
corresponding implementation functions above for the specific behavior of each filter option. :card_index:.
##### PARAMS:
......@@ -295,8 +340,7 @@ Get all the Cards. Option filter param `f` can be used to change the set of Card
* **`model_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `GET /api/card/:id`
### `GET /api/card/:id`
Get `Card` with ID.
......@@ -304,8 +348,7 @@ Get `Card` with ID.
* **`id`**
## `GET /api/card/:id/related`
### `GET /api/card/:id/related`
Return related entities.
......@@ -313,23 +356,20 @@ Return related entities.
* **`id`**
## `GET /api/card/embeddable`
### `GET /api/card/embeddable`
Fetch a list of Cards where `enable_embedding` is `true`. The cards can be embedded using the embedding endpoints
and a signed JWT.
You must be a superuser to do this.
## `GET /api/card/public`
### `GET /api/card/public`
Fetch a list of Cards with public UUIDs. These cards are publicly-accessible *if* public sharing is enabled.
You must be a superuser to do this.
## `POST /api/card/`
### `POST /api/card/`
Create a new `Card`.
......@@ -353,8 +393,7 @@ Create a new `Card`.
* **`display`** value must be a non-blank string.
## `POST /api/card/:card-id/favorite`
### `POST /api/card/:card-id/favorite`
Favorite a Card.
......@@ -362,8 +401,7 @@ Favorite a Card.
* **`card-id`**
## `POST /api/card/:card-id/public_link`
### `POST /api/card/:card-id/public_link`
Generate publicly-accessible links for this Card. Returns UUID to be used in public links. (If this Card has
already been shared, it will return the existing public link rather than creating a new one.) Public sharing must
......@@ -375,8 +413,7 @@ You must be a superuser to do this.
* **`card-id`**
## `POST /api/card/:card-id/query`
### `POST /api/card/:card-id/query`
Run the query associated with a Card.
......@@ -388,11 +425,10 @@ Run the query associated with a Card.
* **`ignore_cache`** value may be nil, or if non-nil, value must be a boolean.
## `POST /api/card/:card-id/query/:export-format`
### `POST /api/card/:card-id/query/:export-format`
Run the query associated with a Card, and return its results as a file in the specified format. Note that this
expects the parameters as serialized JSON in the 'parameters' parameter
expects the parameters as serialized JSON in the 'parameters' parameter.
##### PARAMS:
......@@ -402,8 +438,7 @@ Run the query associated with a Card, and return its results as a file in the sp
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `POST /api/card/collections`
### `POST /api/card/collections`
Bulk update endpoint for Card Collections. Move a set of `Cards` with CARD_IDS into a `Collection` with
COLLECTION_ID, or remove them from any Collections by passing a `null` COLLECTION_ID.
......@@ -414,8 +449,7 @@ Bulk update endpoint for Card Collections. Move a set of `Cards` with CARD_IDS i
* **`collection_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `POST /api/card/pivot/:card-id/query`
### `POST /api/card/pivot/:card-id/query`
Run the query associated with a Card.
......@@ -427,8 +461,7 @@ Run the query associated with a Card.
* **`ignore_cache`** value may be nil, or if non-nil, value must be a boolean.
## `POST /api/card/related`
### `POST /api/card/related`
Return related entities for an ad-hoc query.
......@@ -436,8 +469,7 @@ Return related entities for an ad-hoc query.
* **`query`**
## `PUT /api/card/:id`
### `PUT /api/card/:id`
Update a `Card`.
......@@ -472,7 +504,26 @@ Update a `Card`.
* **`display`** value may be nil, or if non-nil, value must be a non-blank string.
## `GET /api/collection/`
## Collection
`/api/collection` endpoints. By default, these endpoints operate on Collections in the 'default' namespace, which is
the one that has things like Dashboards and Cards. Other namespaces of Collections exist as well, such as the
`:snippet` namespace, (called 'Snippet folders' in the UI). These namespaces are completely independent hierarchies.
To use these endpoints for other Collections namespaces, you can pass the `?namespace=` parameter (e.g.
`?namespace=snippet`).
- [GET /api/collection/](#get-apicollection)
- [GET /api/collection/:id](#get-apicollectionid)
- [GET /api/collection/:id/items](#get-apicollectioniditems)
- [GET /api/collection/graph](#get-apicollectiongraph)
- [GET /api/collection/root](#get-apicollectionroot)
- [GET /api/collection/root/items](#get-apicollectionrootitems)
- [GET /api/collection/tree](#get-apicollectiontree)
- [POST /api/collection/](#post-apicollection)
- [PUT /api/collection/:id](#put-apicollectionid)
- [PUT /api/collection/graph](#put-apicollectiongraph)
### `GET /api/collection/`
Fetch a list of all Collections that the current user has read permissions for (`:can_write` is returned as an
additional property of each Collection so you can tell which of these you have write permissions for.)
......@@ -486,17 +537,15 @@ Fetch a list of all Collections that the current user has read permissions for (
* **`namespace`** value may be nil, or if non-nil, value must be a non-blank string.
### `GET /api/collection/:id`
## `GET /api/collection/:id`
Fetch a specific Collection with standard details added
Fetch a specific Collection with standard details added.
##### PARAMS:
* **`id`**
## `GET /api/collection/:id/items`
### `GET /api/collection/:id/items`
Fetch a specific Collection's items with the following options:
......@@ -504,7 +553,7 @@ Fetch a specific Collection's items with the following options:
* `archived` - when `true`, return archived objects *instead* of unarchived ones. Defaults to `false`.
* `pinned_state` - when `is_pinned`, return pinned objects only.
when `is_not_pinned`, return non pinned objects only.
when `all`, return everything. By default returns everything
when `all`, return everything. By default returns everything.
##### PARAMS:
......@@ -520,8 +569,7 @@ Fetch a specific Collection's items with the following options:
* **`sort_direction`** value may be nil, or if non-nil, value must be one of: `asc`, `desc`.
## `GET /api/collection/graph`
### `GET /api/collection/graph`
Fetch a graph of all Collection Permissions.
......@@ -531,17 +579,15 @@ You must be a superuser to do this.
* **`namespace`** value may be nil, or if non-nil, value must be a non-blank string.
### `GET /api/collection/root`
## `GET /api/collection/root`
Return the 'Root' Collection object with standard details added
Return the 'Root' Collection object with standard details added.
##### PARAMS:
* **`namespace`** value may be nil, or if non-nil, value must be a non-blank string.
## `GET /api/collection/root/items`
### `GET /api/collection/root/items`
Fetch objects that the current user should see at their root level. As mentioned elsewhere, the 'Root' Collection
doesn't actually exist as a row in the application DB: it's simply a virtual Collection where things with no
......@@ -571,8 +617,7 @@ Fetch objects that the current user should see at their root level. As mentioned
* **`sort_direction`** value may be nil, or if non-nil, value must be one of: `asc`, `desc`.
## `GET /api/collection/tree`
### `GET /api/collection/tree`
Similar to `GET /`, but returns Collections in a tree structure, e.g.
......@@ -583,14 +628,13 @@ Similar to `GET /`, but returns Collections in a tree structure, e.g.
:children [{:name "E"}]}
{:name "F"
:children [{:name "G"}]}]}]}
{:name "H"}]
{:name "H"}].
##### PARAMS:
* **`namespace`** value may be nil, or if non-nil, value must be a non-blank string.
## `POST /api/collection/`
### `POST /api/collection/`
Create a new Collection.
......@@ -608,8 +652,7 @@ Create a new Collection.
* **`authority_level`** value may be nil, or if non-nil, value must be one of: `official`.
## `PUT /api/collection/:id`
### `PUT /api/collection/:id`
Modify an existing Collection, including archiving or unarchiving it, or moving it.
......@@ -633,8 +676,7 @@ Modify an existing Collection, including archiving or unarchiving it, or moving
* **`update_collection_tree_authority_level`** value may be nil, or if non-nil, value must be a boolean.
## `PUT /api/collection/graph`
### `PUT /api/collection/graph`
Do a batch update of Collections Permissions by passing in a modified graph.
......@@ -647,7 +689,35 @@ You must be a superuser to do this.
* **`body`** value must be a map.
## `DELETE /api/dashboard/:dashboard-id/public_link`
## Dashboard
/api/dashboard endpoints.
- [DELETE /api/dashboard/:dashboard-id/public_link](#delete-apidashboarddashboard-idpubliclink)
- [DELETE /api/dashboard/:id](#delete-apidashboardid)
- [DELETE /api/dashboard/:id/cards](#delete-apidashboardidcards)
- [DELETE /api/dashboard/:id/favorite](#delete-apidashboardidfavorite)
- [GET /api/dashboard/](#get-apidashboard)
- [GET /api/dashboard/:id](#get-apidashboardid)
- [GET /api/dashboard/:id/params/:param-key/search/:query](#get-apidashboardidparamsparam-keysearchquery)
- [GET /api/dashboard/:id/params/:param-key/values](#get-apidashboardidparamsparam-keyvalues)
- [GET /api/dashboard/:id/related](#get-apidashboardidrelated)
- [GET /api/dashboard/:id/revisions](#get-apidashboardidrevisions)
- [GET /api/dashboard/embeddable](#get-apidashboardembeddable)
- [GET /api/dashboard/params/valid-filter-fields](#get-apidashboardparamsvalid-filter-fields)
- [GET /api/dashboard/public](#get-apidashboardpublic)
- [POST /api/dashboard/](#post-apidashboard)
- [POST /api/dashboard/:dashboard-id/public_link](#post-apidashboarddashboard-idpubliclink)
- [POST /api/dashboard/:from-dashboard-id/copy](#post-apidashboardfrom-dashboard-idcopy)
- [POST /api/dashboard/:id/cards](#post-apidashboardidcards)
- [POST /api/dashboard/:id/favorite](#post-apidashboardidfavorite)
- [POST /api/dashboard/:id/revert](#post-apidashboardidrevert)
- [POST /api/dashboard/save](#post-apidashboardsave)
- [POST /api/dashboard/save/collection/:parent-collection-id](#post-apidashboardsavecollectionparent-collection-id)
- [PUT /api/dashboard/:id](#put-apidashboardid)
- [PUT /api/dashboard/:id/cards](#put-apidashboardidcards)
### `DELETE /api/dashboard/:dashboard-id/public_link`
Delete the publicly-accessible link to this Dashboard.
......@@ -657,8 +727,7 @@ You must be a superuser to do this.
* **`dashboard-id`**
## `DELETE /api/dashboard/:id`
### `DELETE /api/dashboard/:id`
Delete a Dashboard.
......@@ -666,8 +735,7 @@ Delete a Dashboard.
* **`id`**
## `DELETE /api/dashboard/:id/cards`
### `DELETE /api/dashboard/:id/cards`
Remove a `DashboardCard` from a Dashboard.
......@@ -677,8 +745,7 @@ Remove a `DashboardCard` from a Dashboard.
* **`dashcardId`** value must be a valid integer greater than zero.
## `DELETE /api/dashboard/:id/favorite`
### `DELETE /api/dashboard/:id/favorite`
Unfavorite a Dashboard.
......@@ -686,21 +753,19 @@ Unfavorite a Dashboard.
* **`id`**
## `GET /api/dashboard/`
### `GET /api/dashboard/`
Get `Dashboards`. With filter option `f` (default `all`), restrict results as follows:
* `all` - Return all Dashboards.
* `mine` - Return Dashboards created by the current user.
* `archived` - Return Dashboards that have been archived. (By default, these are *excluded*.)
* `archived` - Return Dashboards that have been archived. (By default, these are *excluded*.).
##### PARAMS:
* **`f`** value may be nil, or if non-nil, value must be one of: `all`, `archived`, `mine`.
## `GET /api/dashboard/:id`
### `GET /api/dashboard/:id`
Get Dashboard with ID.
......@@ -708,8 +773,7 @@ Get Dashboard with ID.
* **`id`**
## `GET /api/dashboard/:id/params/:param-key/search/:query`
### `GET /api/dashboard/:id/params/:param-key/search/:query`
Fetch possible values of the parameter whose ID is `:param-key` that contain `:query`. Optionally restrict
these values by passing query parameters like `other-parameter=value` e.g.
......@@ -730,14 +794,13 @@ Fetch possible values of the parameter whose ID is `:param-key` that contain `:q
* **`query-params`**
## `GET /api/dashboard/:id/params/:param-key/values`
### `GET /api/dashboard/:id/params/:param-key/values`
Fetch possible values of the parameter whose ID is `:param-key`. Optionally restrict these values by passing query
parameters like `other-parameter=value` e.g.
;; fetch values for Dashboard 1 parameter 'abc' that are possible when parameter 'def' is set to 100
GET /api/dashboard/1/params/abc/values?def=100
GET /api/dashboard/1/params/abc/values?def=100.
##### PARAMS:
......@@ -747,8 +810,7 @@ Fetch possible values of the parameter whose ID is `:param-key`. Optionally rest
* **`query-params`**
## `GET /api/dashboard/:id/related`
### `GET /api/dashboard/:id/related`
Return related entities.
......@@ -756,8 +818,7 @@ Return related entities.
* **`id`**
## `GET /api/dashboard/:id/revisions`
### `GET /api/dashboard/:id/revisions`
Fetch `Revisions` for Dashboard with ID.
......@@ -765,16 +826,14 @@ Fetch `Revisions` for Dashboard with ID.
* **`id`**
## `GET /api/dashboard/embeddable`
### `GET /api/dashboard/embeddable`
Fetch a list of Dashboards where `enable_embedding` is `true`. The dashboards can be embedded using the embedding
endpoints and a signed JWT.
You must be a superuser to do this.
## `GET /api/dashboard/params/valid-filter-fields`
### `GET /api/dashboard/params/valid-filter-fields`
Utility endpoint for powering Dashboard UI. Given some set of `filtered` Field IDs (presumably Fields used in
parameters) and a set of `filtering` Field IDs that will be used to restrict values of `filtered` Fields, for each
......@@ -795,7 +854,7 @@ Utility endpoint for powering Dashboard UI. Given some set of `filtered` Field I
Results are returned as a map of
`filtered` Field ID -> subset of `filtering` Field IDs that would be used in chain filter query
`filtered` Field ID -> subset of `filtering` Field IDs that would be used in chain filter query.
##### PARAMS:
......@@ -803,16 +862,14 @@ Utility endpoint for powering Dashboard UI. Given some set of `filtered` Field I
* **`filtering`** value may be nil, or if non-nil, value must satisfy one of the following requirements: 1) value must be a valid integer greater than zero. 2) value must be an array. Each value must be a valid integer greater than zero. The array cannot be empty.
## `GET /api/dashboard/public`
### `GET /api/dashboard/public`
Fetch a list of Dashboards with public UUIDs. These dashboards are publicly-accessible *if* public sharing is
enabled.
You must be a superuser to do this.
## `POST /api/dashboard/`
### `POST /api/dashboard/`
Create a new Dashboard.
......@@ -830,8 +887,7 @@ Create a new Dashboard.
* **`dashboard`**
## `POST /api/dashboard/:dashboard-id/public_link`
### `POST /api/dashboard/:dashboard-id/public_link`
Generate publicly-accessible links for this Dashboard. Returns UUID to be used in public links. (If this
Dashboard has already been shared, it will return the existing public link rather than creating a new one.) Public
......@@ -843,8 +899,7 @@ You must be a superuser to do this.
* **`dashboard-id`**
## `POST /api/dashboard/:from-dashboard-id/copy`
### `POST /api/dashboard/:from-dashboard-id/copy`
Copy a Dashboard.
......@@ -862,8 +917,7 @@ Copy a Dashboard.
* **`dashboard`**
## `POST /api/dashboard/:id/cards`
### `POST /api/dashboard/:id/cards`
Add a `Card` to a Dashboard.
......@@ -879,8 +933,7 @@ Add a `Card` to a Dashboard.
* **`dashboard-card`**
## `POST /api/dashboard/:id/favorite`
### `POST /api/dashboard/:id/favorite`
Favorite a Dashboard.
......@@ -888,8 +941,7 @@ Favorite a Dashboard.
* **`id`**
## `POST /api/dashboard/:id/revert`
### `POST /api/dashboard/:id/revert`
Revert a Dashboard to a prior `Revision`.
......@@ -899,8 +951,7 @@ Revert a Dashboard to a prior `Revision`.
* **`revision_id`** value must be an integer greater than zero.
## `POST /api/dashboard/save`
### `POST /api/dashboard/save`
Save a denormalized description of dashboard.
......@@ -908,8 +959,7 @@ Save a denormalized description of dashboard.
* **`dashboard`**
## `POST /api/dashboard/save/collection/:parent-collection-id`
### `POST /api/dashboard/save/collection/:parent-collection-id`
Save a denormalized description of dashboard into collection with ID `:parent-collection-id`.
......@@ -919,8 +969,7 @@ Save a denormalized description of dashboard into collection with ID `:parent-co
* **`dashboard`**
## `PUT /api/dashboard/:id`
### `PUT /api/dashboard/:id`
Update a Dashboard.
......@@ -958,8 +1007,7 @@ Update a Dashboard.
* **`position`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `PUT /api/dashboard/:id/cards`
### `PUT /api/dashboard/:id/cards`
Update `Cards` on a Dashboard. Request body should have the form:
......@@ -969,7 +1017,7 @@ Update `Cards` on a Dashboard. Request body should have the form:
:row ...
:col ...
:series [{:id 123
...}]} ...]}
...}]} ...]}.
##### PARAMS:
......@@ -978,7 +1026,34 @@ Update `Cards` on a Dashboard. Request body should have the form:
* **`cards`**
## `DELETE /api/database/:id`
## Database
/api/database endpoints.
- [DELETE /api/database/:id](#delete-apidatabaseid)
- [GET /api/database/](#get-apidatabase)
- [GET /api/database/:id](#get-apidatabaseid)
- [GET /api/database/:id/autocomplete_suggestions](#get-apidatabaseidautocompletesuggestions)
- [GET /api/database/:id/fields](#get-apidatabaseidfields)
- [GET /api/database/:id/idfields](#get-apidatabaseididfields)
- [GET /api/database/:id/metadata](#get-apidatabaseidmetadata)
- [GET /api/database/:id/schema/](#get-apidatabaseidschema)
- [GET /api/database/:id/schema/:schema](#get-apidatabaseidschemaschema)
- [GET /api/database/:id/schemas](#get-apidatabaseidschemas)
- [GET /api/database/:virtual-db/metadata](#get-apidatabasevirtual-dbmetadata)
- [GET /api/database/:virtual-db/schema/:schema](#get-apidatabasevirtual-dbschemaschema)
- [GET /api/database/:virtual-db/schemas](#get-apidatabasevirtual-dbschemas)
- [GET /api/database/db-ids-with-deprecated-drivers](#get-apidatabasedb-ids-with-deprecated-drivers)
- [POST /api/database/](#post-apidatabase)
- [POST /api/database/:id/discard_values](#post-apidatabaseiddiscardvalues)
- [POST /api/database/:id/rescan_values](#post-apidatabaseidrescanvalues)
- [POST /api/database/:id/sync](#post-apidatabaseidsync)
- [POST /api/database/:id/sync_schema](#post-apidatabaseidsyncschema)
- [POST /api/database/sample_dataset](#post-apidatabasesampledataset)
- [POST /api/database/validate](#post-apidatabasevalidate)
- [PUT /api/database/:id](#put-apidatabaseid)
### `DELETE /api/database/:id`
Delete a `Database`.
......@@ -986,8 +1061,7 @@ Delete a `Database`.
* **`id`**
## `GET /api/database/`
### `GET /api/database/`
Fetch all `Databases`.
......@@ -1000,7 +1074,7 @@ Fetch all `Databases`.
* `include_cards` here means we should also include virtual Table entries for saved Questions, e.g. so we can easily
use them as source Tables in queries. This is a deprecated alias for `saved=true` + `include=tables` (for the saved
questions virtual DB). Prefer using `include` and `saved` instead.
questions virtual DB). Prefer using `include` and `saved` instead. .
##### PARAMS:
......@@ -1012,8 +1086,7 @@ Fetch all `Databases`.
* **`saved`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
## `GET /api/database/:id`
### `GET /api/database/:id`
Get a single Database with `id`. Optionally pass `?include=tables` or `?include=tables.fields` to include the Tables
belonging to this database, or the Tables and Fields, respectively.
......@@ -1024,8 +1097,7 @@ Get a single Database with `id`. Optionally pass `?include=tables` or `?include=
* **`include`** value may be nil, or if non-nil, value must be one of: `tables`, `tables.fields`.
## `GET /api/database/:id/autocomplete_suggestions`
### `GET /api/database/:id/autocomplete_suggestions`
Return a list of autocomplete suggestions for a given `prefix`.
......@@ -1033,7 +1105,7 @@ Return a list of autocomplete suggestions for a given `prefix`.
and `Fields` in this `Database`.
Tables are returned in the format `[table_name "Table"]`;
Fields are returned in the format `[field_name "table_name base_type semantic_type"]`
Fields are returned in the format `[field_name "table_name base_type semantic_type"]`.
##### PARAMS:
......@@ -1041,8 +1113,7 @@ Return a list of autocomplete suggestions for a given `prefix`.
* **`prefix`** value must be a non-blank string.
## `GET /api/database/:id/fields`
### `GET /api/database/:id/fields`
Get a list of all `Fields` in `Database`.
......@@ -1050,8 +1121,7 @@ Get a list of all `Fields` in `Database`.
* **`id`**
## `GET /api/database/:id/idfields`
### `GET /api/database/:id/idfields`
Get a list of all primary key `Fields` for `Database`.
......@@ -1059,8 +1129,7 @@ Get a list of all primary key `Fields` for `Database`.
* **`id`**
## `GET /api/database/:id/metadata`
### `GET /api/database/:id/metadata`
Get metadata about a `Database`, including all of its `Tables` and `Fields`.
By default only non-hidden tables and fields are returned. Passing include_hidden=true includes them.
......@@ -1072,8 +1141,7 @@ Get metadata about a `Database`, including all of its `Tables` and `Fields`.
* **`include_hidden`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
## `GET /api/database/:id/schema/`
### `GET /api/database/:id/schema/`
Return a list of Tables for a Database whose `schema` is `nil` or an empty string.
......@@ -1081,10 +1149,9 @@ Return a list of Tables for a Database whose `schema` is `nil` or an empty strin
* **`id`**
### `GET /api/database/:id/schema/:schema`
## `GET /api/database/:id/schema/:schema`
Returns a list of Tables for the given Database `id` and `schema`
Returns a list of Tables for the given Database `id` and `schema`.
##### PARAMS:
......@@ -1092,23 +1159,20 @@ Returns a list of Tables for the given Database `id` and `schema`
* **`schema`**
### `GET /api/database/:id/schemas`
## `GET /api/database/:id/schemas`
Returns a list of all the schemas found for the database `id`
Returns a list of all the schemas found for the database `id`.
##### PARAMS:
* **`id`**
## `GET /api/database/:virtual-db/metadata`
### `GET /api/database/:virtual-db/metadata`
Endpoint that provides metadata for the Saved Questions 'virtual' database. Used for fooling the frontend
and allowing it to treat the Saved Questions virtual DB just like any other database.
## `GET /api/database/:virtual-db/schema/:schema`
### `GET /api/database/:virtual-db/schema/:schema`
Returns a list of Tables for the saved questions virtual database.
......@@ -1116,13 +1180,15 @@ Returns a list of Tables for the saved questions virtual database.
* **`schema`**
## `GET /api/database/:virtual-db/schemas`
### `GET /api/database/:virtual-db/schemas`
Returns a list of all the schemas found for the saved questions virtual database.
### `GET /api/database/db-ids-with-deprecated-drivers`
## `POST /api/database/`
Return a list of database IDs using currently deprecated drivers.
### `POST /api/database/`
Add a new `Database`.
......@@ -1144,8 +1210,7 @@ You must be a superuser to do this.
* **`auto_run_queries`** value may be nil, or if non-nil, value must be a boolean.
## `POST /api/database/:id/discard_values`
### `POST /api/database/:id/discard_values`
Discards all saved field values for this `Database`.
......@@ -1155,8 +1220,7 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/database/:id/rescan_values`
### `POST /api/database/:id/rescan_values`
Trigger a manual scan of the field values for this `Database`.
......@@ -1166,8 +1230,7 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/database/:id/sync`
### `POST /api/database/:id/sync`
Update the metadata for this `Database`. This happens asynchronously.
......@@ -1175,8 +1238,7 @@ Update the metadata for this `Database`. This happens asynchronously.
* **`id`**
## `POST /api/database/:id/sync_schema`
### `POST /api/database/:id/sync_schema`
Trigger a manual update of the schema metadata for this `Database`.
......@@ -1186,15 +1248,13 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/database/sample_dataset`
### `POST /api/database/sample_dataset`
Add the sample dataset as a new `Database`.
You must be a superuser to do this.
## `POST /api/database/validate`
### `POST /api/database/validate`
Validate that we can connect to a database given a set of details.
......@@ -1206,8 +1266,7 @@ You must be a superuser to do this.
* **`details`** value must be a map.
## `PUT /api/database/:id`
### `PUT /api/database/:id`
Update a `Database`.
......@@ -1240,7 +1299,17 @@ You must be a superuser to do this.
* **`is_on_demand`**
## `POST /api/dataset/`
## Dataset
/api/dataset endpoints.
- [POST /api/dataset/](#post-apidataset)
- [POST /api/dataset/:export-format](#post-apidatasetexport-format)
- [POST /api/dataset/duration](#post-apidatasetduration)
- [POST /api/dataset/native](#post-apidatasetnative)
- [POST /api/dataset/pivot](#post-apidatasetpivot)
### `POST /api/dataset/`
Execute a query and retrieve the results in the usual format.
......@@ -1252,8 +1321,7 @@ Execute a query and retrieve the results in the usual format.
* **`query`**
## `POST /api/dataset/:export-format`
### `POST /api/dataset/:export-format`
Execute a query and download the result data as a file in the specified format.
......@@ -1263,8 +1331,9 @@ Execute a query and download the result data as a file in the specified format.
* **`query`** value must be a valid JSON string.
* **`visualization_settings`** value must be a valid JSON string.
## `POST /api/dataset/duration`
### `POST /api/dataset/duration`
Get historical query execution duration.
......@@ -1274,8 +1343,7 @@ Get historical query execution duration.
* **`query`**
## `POST /api/dataset/native`
### `POST /api/dataset/native`
Fetch a native version of an MBQL query.
......@@ -1283,10 +1351,9 @@ Fetch a native version of an MBQL query.
* **`query`**
### `POST /api/dataset/pivot`
## `POST /api/dataset/pivot`
Generate a pivoted dataset for an ad-hoc query
Generate a pivoted dataset for an ad-hoc query.
##### PARAMS:
......@@ -1297,21 +1364,28 @@ Generate a pivoted dataset for an ad-hoc query
* **`query`**
## `DELETE /api/email/`
## Email
Clear all email related settings. You must be a superuser to ddo this
/api/email endpoints.
You must be a superuser to do this.
- [DELETE /api/email/](#delete-apiemail)
- [POST /api/email/test](#post-apiemailtest)
- [PUT /api/email/](#put-apiemail)
### `DELETE /api/email/`
## `POST /api/email/test`
Send a test email. You must be a superuser to do this.
Clear all email related settings. You must be a superuser to ddo this.
You must be a superuser to do this.
### `POST /api/email/test`
## `PUT /api/email/`
Send a test email using the SMTP Settings. You must be a superuser to do this. Returns `{:ok true}` if we were able
to send the message successfully, otherwise a standard 400 error response.
You must be a superuser to do this.
### `PUT /api/email/`
Update multiple email Settings. You must be a superuser to do this.
......@@ -1322,20 +1396,54 @@ You must be a superuser to do this.
* **`settings`** value must be a map.
## `GET /api/embed/card/:token`
## Embed
Various endpoints that use [JSON web tokens](https://jwt.io/introduction/) to fetch Cards and Dashboards.
The endpoints are the same as the ones in `api/public/`, and differ only in the way they are authorized.
To use these endpoints:
1. Set the `embedding-secret-key` Setting to a hexadecimal-encoded 32-byte sequence (i.e., a 64-character string).
You can use `/api/util/random_token` to get a cryptographically-secure value for this.
2. Sign/base-64 encode a JSON Web Token using the secret key and pass it as the relevant part of the URL path
to the various endpoints here.
Tokens can have the following fields:
{:resource {:question <card-id>
:dashboard <dashboard-id>}
:params <params>}.
- [GET /api/embed/card/:token](#get-apiembedcardtoken)
- [GET /api/embed/card/:token/field/:field-id/remapping/:remapped-id](#get-apiembedcardtokenfieldfield-idremappingremapped-id)
- [GET /api/embed/card/:token/field/:field-id/search/:search-field-id](#get-apiembedcardtokenfieldfield-idsearchsearch-field-id)
- [GET /api/embed/card/:token/field/:field-id/values](#get-apiembedcardtokenfieldfield-idvalues)
- [GET /api/embed/card/:token/query](#get-apiembedcardtokenquery)
- [GET /api/embed/card/:token/query/:export-format](#get-apiembedcardtokenqueryexport-format)
- [GET /api/embed/dashboard/:token](#get-apiembeddashboardtoken)
- [GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id](#get-apiembeddashboardtokendashcarddashcard-idcardcard-id)
- [GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id/:export-format](#get-apiembeddashboardtokendashcarddashcard-idcardcard-idexport-format)
- [GET /api/embed/dashboard/:token/field/:field-id/remapping/:remapped-id](#get-apiembeddashboardtokenfieldfield-idremappingremapped-id)
- [GET /api/embed/dashboard/:token/field/:field-id/search/:search-field-id](#get-apiembeddashboardtokenfieldfield-idsearchsearch-field-id)
- [GET /api/embed/dashboard/:token/field/:field-id/values](#get-apiembeddashboardtokenfieldfield-idvalues)
- [GET /api/embed/dashboard/:token/params/:param-key/search/:prefix](#get-apiembeddashboardtokenparamsparam-keysearchprefix)
- [GET /api/embed/dashboard/:token/params/:param-key/values](#get-apiembeddashboardtokenparamsparam-keyvalues)
- [GET /api/embed/pivot/card/:token/query](#get-apiembedpivotcardtokenquery)
- [GET /api/embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id](#get-apiembedpivotdashboardtokendashcarddashcard-idcardcard-id)
### `GET /api/embed/card/:token`
Fetch a Card via a JSON Web Token signed with the `embedding-secret-key`.
Token should have the following format:
{:resource {:question <card-id>}}
{:resource {:question <card-id>}}.
##### PARAMS:
* **`token`**
## `GET /api/embed/card/:token/field/:field-id/remapping/:remapped-id`
### `GET /api/embed/card/:token/field/:field-id/remapping/:remapped-id`
Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:remapped-id`, but for use with
embedded Cards.
......@@ -1350,8 +1458,7 @@ Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:
* **`value`** value must be a non-blank string.
## `GET /api/embed/card/:token/field/:field-id/search/:search-field-id`
### `GET /api/embed/card/:token/field/:field-id/search/:search-field-id`
Search for values of a Field that is referenced by an embedded Card.
......@@ -1367,8 +1474,7 @@ Search for values of a Field that is referenced by an embedded Card.
* **`limit`** value may be nil, or if non-nil, value must be a valid integer greater than zero.
## `GET /api/embed/card/:token/field/:field-id/values`
### `GET /api/embed/card/:token/field/:field-id/values`
Fetch FieldValues for a Field that is referenced by an embedded Card.
......@@ -1378,15 +1484,14 @@ Fetch FieldValues for a Field that is referenced by an embedded Card.
* **`field-id`**
## `GET /api/embed/card/:token/query`
### `GET /api/embed/card/:token/query`
Fetch the results of running a Card using a JSON Web Token signed with the `embedding-secret-key`.
Token should have the following format:
{:resource {:question <card-id>}
:params <parameters>}
:params <parameters>}.
##### PARAMS:
......@@ -1396,8 +1501,7 @@ Fetch the results of running a Card using a JSON Web Token signed with the `embe
* **`query-params`**
## `GET /api/embed/card/:token/query/:export-format`
### `GET /api/embed/card/:token/query/:export-format`
Like `GET /api/embed/card/query`, but returns the results as a file in the specified format.
......@@ -1409,24 +1513,22 @@ Like `GET /api/embed/card/query`, but returns the results as a file in the speci
* **`query-params`**
## `GET /api/embed/dashboard/:token`
### `GET /api/embed/dashboard/:token`
Fetch a Dashboard via a JSON Web Token signed with the `embedding-secret-key`.
Token should have the following format:
{:resource {:dashboard <dashboard-id>}}
{:resource {:dashboard <dashboard-id>}}.
##### PARAMS:
* **`token`**
## `GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
### `GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
Fetch the results of running a Card belonging to a Dashboard using a JSON Web Token signed with the
`embedding-secret-key`
`embedding-secret-key`.
##### PARAMS:
......@@ -1440,11 +1542,10 @@ Fetch the results of running a Card belonging to a Dashboard using a JSON Web To
* **`query-params`**
## `GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id/:export-format`
### `GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id/:export-format`
Fetch the results of running a Card belonging to a Dashboard using a JSON Web Token signed with the
`embedding-secret-key` return the data in one of the export formats
`embedding-secret-key` return the data in one of the export formats.
##### PARAMS:
......@@ -1458,8 +1559,7 @@ Fetch the results of running a Card belonging to a Dashboard using a JSON Web To
* **`query-params`**
## `GET /api/embed/dashboard/:token/field/:field-id/remapping/:remapped-id`
### `GET /api/embed/dashboard/:token/field/:field-id/remapping/:remapped-id`
Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:remapped-id`, but for use with
embedded Dashboards.
......@@ -1474,8 +1574,7 @@ Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:
* **`value`** value must be a non-blank string.
## `GET /api/embed/dashboard/:token/field/:field-id/search/:search-field-id`
### `GET /api/embed/dashboard/:token/field/:field-id/search/:search-field-id`
Search for values of a Field that is referenced by a Card in an embedded Dashboard.
......@@ -1491,8 +1590,7 @@ Search for values of a Field that is referenced by a Card in an embedded Dashboa
* **`limit`** value may be nil, or if non-nil, value must be a valid integer greater than zero.
## `GET /api/embed/dashboard/:token/field/:field-id/values`
### `GET /api/embed/dashboard/:token/field/:field-id/values`
Fetch FieldValues for a Field that is used as a param in an embedded Dashboard.
......@@ -1502,8 +1600,7 @@ Fetch FieldValues for a Field that is used as a param in an embedded Dashboard.
* **`field-id`**
## `GET /api/embed/dashboard/:token/params/:param-key/search/:prefix`
### `GET /api/embed/dashboard/:token/params/:param-key/search/:prefix`
Embedded version of chain filter search endpoint.
......@@ -1517,8 +1614,7 @@ Embedded version of chain filter search endpoint.
* **`query-params`**
## `GET /api/embed/dashboard/:token/params/:param-key/values`
### `GET /api/embed/dashboard/:token/params/:param-key/values`
Embedded version of chain filter values endpoint.
......@@ -1530,15 +1626,14 @@ Embedded version of chain filter values endpoint.
* **`query-params`**
## `GET /api/embed/pivot/card/:token/query`
### `GET /api/embed/pivot/card/:token/query`
Fetch the results of running a Card using a JSON Web Token signed with the `embedding-secret-key`.
Token should have the following format:
{:resource {:question <card-id>}
:params <parameters>}
:params <parameters>}.
##### PARAMS:
......@@ -1548,11 +1643,10 @@ Fetch the results of running a Card using a JSON Web Token signed with the `embe
* **`query-params`**
## `GET /api/embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
### `GET /api/embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
Fetch the results of running a Card belonging to a Dashboard using a JSON Web Token signed with the
`embedding-secret-key`
`embedding-secret-key`.
##### PARAMS:
......@@ -1567,16 +1661,31 @@ Fetch the results of running a Card belonging to a Dashboard using a JSON Web To
* **`query-params`**
## `DELETE /api/field/:id/dimension`
## Field
Remove the dimension associated to field at ID
- [DELETE /api/field/:id/dimension](#delete-apifieldiddimension)
- [GET /api/field/:id](#get-apifieldid)
- [GET /api/field/:id/related](#get-apifieldidrelated)
- [GET /api/field/:id/remapping/:remapped-id](#get-apifieldidremappingremapped-id)
- [GET /api/field/:id/search/:search-id](#get-apifieldidsearchsearch-id)
- [GET /api/field/:id/summary](#get-apifieldidsummary)
- [GET /api/field/:id/values](#get-apifieldidvalues)
- [GET /api/field/field%2C:field-name%2C:options/values](#get-apifieldfield%2cfield-name%2coptionsvalues)
- [POST /api/field/:id/dimension](#post-apifieldiddimension)
- [POST /api/field/:id/discard_values](#post-apifieldiddiscardvalues)
- [POST /api/field/:id/rescan_values](#post-apifieldidrescanvalues)
- [POST /api/field/:id/values](#post-apifieldidvalues)
- [PUT /api/field/:id](#put-apifieldid)
### `DELETE /api/field/:id/dimension`
Remove the dimension associated to field at ID.
##### PARAMS:
* **`id`**
## `GET /api/field/:id`
### `GET /api/field/:id`
Get `Field` with ID.
......@@ -1584,8 +1693,7 @@ Get `Field` with ID.
* **`id`**
## `GET /api/field/:id/related`
### `GET /api/field/:id/related`
Return related entities.
......@@ -1593,8 +1701,7 @@ Return related entities.
* **`id`**
## `GET /api/field/:id/remapping/:remapped-id`
### `GET /api/field/:id/remapping/:remapped-id`
Fetch remapped Field values.
......@@ -1606,8 +1713,7 @@ Fetch remapped Field values.
* **`value`**
## `GET /api/field/:id/search/:search-id`
### `GET /api/field/:id/search/:search-id`
Search for values of a Field with `search-id` that start with `value`. See docstring for
`metabase.api.field/search-values` for a more detailed explanation.
......@@ -1620,10 +1726,7 @@ Search for values of a Field with `search-id` that start with `value`. See docst
* **`value`** value must be a non-blank string.
* **`limit`** value may be nil, or if non-nil, value must be a valid integer greater than zero.
## `GET /api/field/:id/summary`
### `GET /api/field/:id/summary`
Get the count and distinct count of `Field` with ID.
......@@ -1631,8 +1734,7 @@ Get the count and distinct count of `Field` with ID.
* **`id`**
## `GET /api/field/:id/values`
### `GET /api/field/:id/values`
If a Field's value of `has_field_values` is `list`, return a list of all the distinct values of the Field, and (if
defined by a User) a map of human-readable remapped values.
......@@ -1641,8 +1743,7 @@ If a Field's value of `has_field_values` is `list`, return a list of all the dis
* **`id`**
## `GET /api/field/field%2C:field-name%2C:options/values`
### `GET /api/field/field%2C:field-name%2C:options/values`
Implementation of the field values endpoint for fields in the Saved Questions 'virtual' DB. This endpoint is just a
convenience to simplify the frontend code. It just returns the standard 'empty' field values response.
......@@ -1651,10 +1752,9 @@ Implementation of the field values endpoint for fields in the Saved Questions 'v
* **`_`**
### `POST /api/field/:id/dimension`
## `POST /api/field/:id/dimension`
Sets the dimension for the given field at ID
Sets the dimension for the given field at ID.
##### PARAMS:
......@@ -1666,8 +1766,7 @@ Sets the dimension for the given field at ID
* **`human_readable_field_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `POST /api/field/:id/discard_values`
### `POST /api/field/:id/discard_values`
Discard the FieldValues belonging to this Field. Only applies to fields that have FieldValues. If this Field's
Database is set up to automatically sync FieldValues, they will be recreated during the next cycle.
......@@ -1678,8 +1777,7 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/field/:id/rescan_values`
### `POST /api/field/:id/rescan_values`
Manually trigger an update for the FieldValues for this Field. Only applies to Fields that are eligible for
FieldValues.
......@@ -1690,8 +1788,7 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/field/:id/values`
### `POST /api/field/:id/values`
Update the fields values and human-readable values for a `Field` whose semantic type is
`category`/`city`/`state`/`country` or whose base type is `type/Boolean`. The human-readable values are optional.
......@@ -1702,8 +1799,7 @@ Update the fields values and human-readable values for a `Field` whose semantic
* **`value-pairs`** value must be an array. Each value must be an array.
## `PUT /api/field/:id`
### `PUT /api/field/:id`
Update `Field` with ID.
......@@ -1732,7 +1828,12 @@ Update `Field` with ID.
* **`id`**
## `GET /api/geojson/`
## Geojson
- [GET /api/geojson/](#get-apigeojson)
- [GET /api/geojson/:key](#get-apigeojsonkey)
### `GET /api/geojson/`
Load a custom GeoJSON file based on a URL or file path provided as a query parameter.
This behaves similarly to /api/geojson/:key but doesn't require the custom map to be saved to the DB first.
......@@ -1745,8 +1846,7 @@ Load a custom GeoJSON file based on a URL or file path provided as a query param
* **`raise`**
## `GET /api/geojson/:key`
### `GET /api/geojson/:key`
Fetch a custom GeoJSON file as defined in the `custom-geojson` setting. (This just acts as a simple proxy for the
file specified for `key`).
......@@ -1760,7 +1860,13 @@ Fetch a custom GeoJSON file as defined in the `custom-geojson` setting. (This ju
* **`raise`**
## `PUT /api/ldap/settings`
## Ldap
/api/ldap endpoints.
- [PUT /api/ldap/settings](#put-apildapsettings)
### `PUT /api/ldap/settings`
Update LDAP related settings. You must be a superuser to do this.
......@@ -1771,20 +1877,42 @@ You must be a superuser to do this.
* **`settings`** value must be a map.
## `GET /api/login-history/current`
## Login history
- [GET /api/login-history/current](#get-apilogin-historycurrent)
### `GET /api/login-history/current`
Fetch recent logins for the current user.
## `GET /api/metastore/token/status`
## Metastore
- [GET /api/metastore/token/status](#get-apimetastoretokenstatus)
### `GET /api/metastore/token/status`
Fetch info about the current MetaStore premium features token including whether it is `valid`, a `trial` token, its
`features`, and when it is `valid_thru`.
## `DELETE /api/metric/:id`
## Metric
/api/metric endpoints.
- [DELETE /api/metric/:id](#delete-apimetricid)
- [GET /api/metric/](#get-apimetric)
- [GET /api/metric/:id](#get-apimetricid)
- [GET /api/metric/:id/related](#get-apimetricidrelated)
- [GET /api/metric/:id/revisions](#get-apimetricidrevisions)
- [POST /api/metric/](#post-apimetric)
- [POST /api/metric/:id/revert](#post-apimetricidrevert)
- [PUT /api/metric/:id](#put-apimetricid)
- [PUT /api/metric/:id/important_fields](#put-apimetricidimportantfields)
### `DELETE /api/metric/:id`
Archive a Metric. (DEPRECATED -- Just pass updated value of `:archived` to the `PUT` endpoint instead.)
Archive a Metric. (DEPRECATED -- Just pass updated value of `:archived` to the `PUT` endpoint instead.).
##### PARAMS:
......@@ -1792,8 +1920,7 @@ Archive a Metric. (DEPRECATED -- Just pass updated value of `:archived` to the `
* **`revision_message`** value must be a non-blank string.
## `GET /api/metric/`
### `GET /api/metric/`
Fetch *all* `Metrics`.
......@@ -1801,8 +1928,7 @@ Fetch *all* `Metrics`.
* **`id`**
## `GET /api/metric/:id`
### `GET /api/metric/:id`
Fetch `Metric` with ID.
......@@ -1810,8 +1936,7 @@ Fetch `Metric` with ID.
* **`id`**
## `GET /api/metric/:id/related`
### `GET /api/metric/:id/related`
Return related entities.
......@@ -1819,8 +1944,7 @@ Return related entities.
* **`id`**
## `GET /api/metric/:id/revisions`
### `GET /api/metric/:id/revisions`
Fetch `Revisions` for `Metric` with ID.
......@@ -1828,8 +1952,7 @@ Fetch `Revisions` for `Metric` with ID.
* **`id`**
## `POST /api/metric/`
### `POST /api/metric/`
Create a new `Metric`.
......@@ -1843,8 +1966,7 @@ Create a new `Metric`.
* **`definition`** value must be a map.
## `POST /api/metric/:id/revert`
### `POST /api/metric/:id/revert`
Revert a `Metric` to a prior `Revision`.
......@@ -1854,8 +1976,7 @@ Revert a `Metric` to a prior `Revision`.
* **`revision_id`** value must be an integer greater than zero.
## `PUT /api/metric/:id`
### `PUT /api/metric/:id`
Update a `Metric` with ID.
......@@ -1881,8 +2002,7 @@ Update a `Metric` with ID.
* **`how_is_this_calculated`** value may be nil, or if non-nil, value must be a string.
## `PUT /api/metric/:id/important_fields`
### `PUT /api/metric/:id/important_fields`
Update the important `Fields` for a `Metric` with ID.
(This is used for the Getting Started guide).
......@@ -1896,16 +2016,24 @@ You must be a superuser to do this.
* **`important_field_ids`** value must be an array. Each value must be an integer greater than zero.
## `GET /api/native-query-snippet/`
## Native query snippet
Native query snippet (/api/native-query-snippet) endpoints.
- [GET /api/native-query-snippet/](#get-apinative-query-snippet)
- [GET /api/native-query-snippet/:id](#get-apinative-query-snippetid)
- [POST /api/native-query-snippet/](#post-apinative-query-snippet)
- [PUT /api/native-query-snippet/:id](#put-apinative-query-snippetid)
Fetch all snippets
### `GET /api/native-query-snippet/`
Fetch all snippets.
##### PARAMS:
* **`archived`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
## `GET /api/native-query-snippet/:id`
### `GET /api/native-query-snippet/:id`
Fetch native query snippet with ID.
......@@ -1913,8 +2041,7 @@ Fetch native query snippet with ID.
* **`id`**
## `POST /api/native-query-snippet/`
### `POST /api/native-query-snippet/`
Create a new `NativeQuerySnippet`.
......@@ -1928,8 +2055,7 @@ Create a new `NativeQuerySnippet`.
* **`collection_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `PUT /api/native-query-snippet/:id`
### `PUT /api/native-query-snippet/:id`
Update an existing `NativeQuerySnippet`.
......@@ -1948,14 +2074,20 @@ Update an existing `NativeQuerySnippet`.
* **`collection_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `POST /api/notify/db/:id`
## Notify
/api/notify/* endpoints which receive inbound etl server notifications.
- [POST /api/notify/db/:id](#post-apinotifydbid)
### `POST /api/notify/db/:id`
Notification about a potential schema change to one of our `Databases`.
Caller can optionally specify a `:table_id` or `:table_name` in the body to limit updates to a single
`Table`. Optional Parameter `:scan` can be `"full"` or `"schema"` for a full sync or a schema sync, available
regardless if a `:table_id` or `:table_name` is passed.
This endpoint is secured by an API key that needs to be passed as a `X-METABASE-APIKEY` header which needs to be defined in
the `MB_API_KEY` [environment variable](https://www.metabase.com/docs/latest/operations-guide/environment-variables.html#mb_api_key)
the `MB_API_KEY` [environment variable](https://www.metabase.com/docs/latest/operations-guide/environment-variables.html#mb_api_key).
##### PARAMS:
......@@ -1968,7 +2100,22 @@ Notification about a potential schema change to one of our `Databases`.
* **`scan`** value may be nil, or if non-nil, value must be one of: `full`, `schema`.
## `DELETE /api/permissions/group/:group-id`
## Permissions
/api/permissions endpoints.
- [DELETE /api/permissions/group/:group-id](#delete-apipermissionsgroupgroup-id)
- [DELETE /api/permissions/membership/:id](#delete-apipermissionsmembershipid)
- [GET /api/permissions/graph](#get-apipermissionsgraph)
- [GET /api/permissions/group](#get-apipermissionsgroup)
- [GET /api/permissions/group/:id](#get-apipermissionsgroupid)
- [GET /api/permissions/membership](#get-apipermissionsmembership)
- [POST /api/permissions/group](#post-apipermissionsgroup)
- [POST /api/permissions/membership](#post-apipermissionsmembership)
- [PUT /api/permissions/graph](#put-apipermissionsgraph)
- [PUT /api/permissions/group/:group-id](#put-apipermissionsgroupgroup-id)
### `DELETE /api/permissions/group/:group-id`
Delete a specific `PermissionsGroup`.
......@@ -1978,8 +2125,7 @@ You must be a superuser to do this.
* **`group-id`**
## `DELETE /api/permissions/membership/:id`
### `DELETE /api/permissions/membership/:id`
Remove a User from a PermissionsGroup (delete their membership).
......@@ -1989,22 +2135,19 @@ You must be a superuser to do this.
* **`id`**
## `GET /api/permissions/graph`
### `GET /api/permissions/graph`
Fetch a graph of all Permissions.
You must be a superuser to do this.
## `GET /api/permissions/group`
### `GET /api/permissions/group`
Fetch all `PermissionsGroups`, including a count of the number of `:members` in that group.
You must be a superuser to do this.
## `GET /api/permissions/group/:id`
### `GET /api/permissions/group/:id`
Fetch the details for a certain permissions group.
......@@ -2014,19 +2157,17 @@ You must be a superuser to do this.
* **`id`**
## `GET /api/permissions/membership`
### `GET /api/permissions/membership`
Fetch a map describing the group memberships of various users.
This map's format is:
{<user-id> [{:membership_id <id>
:group_id <id>}]}
:group_id <id>}]}.
You must be a superuser to do this.
## `POST /api/permissions/group`
### `POST /api/permissions/group`
Create a new `PermissionsGroup`.
......@@ -2036,8 +2177,7 @@ You must be a superuser to do this.
* **`name`** value must be a non-blank string.
## `POST /api/permissions/membership`
### `POST /api/permissions/membership`
Add a `User` to a `PermissionsGroup`. Returns updated list of members belonging to the group.
......@@ -2049,8 +2189,7 @@ You must be a superuser to do this.
* **`user_id`** value must be an integer greater than zero.
## `PUT /api/permissions/graph`
### `PUT /api/permissions/graph`
Do a batch update of Permissions by passing in a modified graph. This should return the same graph, in the same
format, that you got from `GET /api/permissions/graph`, with any changes made in the wherever necessary. This
......@@ -2067,8 +2206,7 @@ You must be a superuser to do this.
* **`body`** value must be a map.
## `PUT /api/permissions/group/:group-id`
### `PUT /api/permissions/group/:group-id`
Update the name of a `PermissionsGroup`.
......@@ -2081,7 +2219,26 @@ You must be a superuser to do this.
* **`name`** value must be a non-blank string.
## `GET /api/preview-embed/card/:token`
## Preview embed
Endpoints for previewing how Cards and Dashboards will look when embedding them.
These endpoints are basically identical in functionality to the ones in `/api/embed`, but:
1. Require admin access
2. Ignore the values of `:enabled_embedding` for Cards/Dashboards
3. Ignore the `:embed_params` whitelist for Card/Dashboards, instead using a field called `:_embedding_params` in
the JWT token itself.
Refer to the documentation for those endpoints for further details.
- [GET /api/preview-embed/card/:token](#get-apipreview-embedcardtoken)
- [GET /api/preview-embed/card/:token/query](#get-apipreview-embedcardtokenquery)
- [GET /api/preview-embed/dashboard/:token](#get-apipreview-embeddashboardtoken)
- [GET /api/preview-embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id](#get-apipreview-embeddashboardtokendashcarddashcard-idcardcard-id)
- [GET /api/preview-embed/pivot/card/:token/query](#get-apipreview-embedpivotcardtokenquery)
- [GET /api/preview-embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id](#get-apipreview-embedpivotdashboardtokendashcarddashcard-idcardcard-id)
### `GET /api/preview-embed/card/:token`
Fetch a Card you're considering embedding by passing a JWT `token`.
......@@ -2089,8 +2246,7 @@ Fetch a Card you're considering embedding by passing a JWT `token`.
* **`token`**
## `GET /api/preview-embed/card/:token/query`
### `GET /api/preview-embed/card/:token/query`
Fetch the query results for a Card you're considering embedding by passing a JWT `token`.
......@@ -2102,17 +2258,15 @@ Fetch the query results for a Card you're considering embedding by passing a JWT
* **`query-params`**
### `GET /api/preview-embed/dashboard/:token`
## `GET /api/preview-embed/dashboard/:token`
Fetch a Dashboard you're considering embedding by passing a JWT `token`.
Fetch a Dashboard you're considering embedding by passing a JWT `token`. .
##### PARAMS:
* **`token`**
## `GET /api/preview-embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
### `GET /api/preview-embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
Fetch the results of running a Card belonging to a Dashboard you're considering embedding with JWT `token`.
......@@ -2128,8 +2282,7 @@ Fetch the results of running a Card belonging to a Dashboard you're considering
* **`query-params`**
## `GET /api/preview-embed/pivot/card/:token/query`
### `GET /api/preview-embed/pivot/card/:token/query`
Fetch the query results for a Card you're considering embedding by passing a JWT `token`.
......@@ -2141,8 +2294,7 @@ Fetch the query results for a Card you're considering embedding by passing a JWT
* **`query-params`**
## `GET /api/preview-embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
### `GET /api/preview-embed/pivot/dashboard/:token/dashcard/:dashcard-id/card/:card-id`
Fetch the results of running a Card belonging to a Dashboard you're considering embedding with JWT `token`.
......@@ -2159,7 +2311,28 @@ Fetch the results of running a Card belonging to a Dashboard you're considering
* **`query-params`**
## `GET /api/public/card/:uuid`
## Public
Metabase API endpoints for viewing publicly-accessible Cards and Dashboards.
- [GET /api/public/card/:uuid](#get-apipubliccarduuid)
- [GET /api/public/card/:uuid/field/:field-id/remapping/:remapped-id](#get-apipubliccarduuidfieldfield-idremappingremapped-id)
- [GET /api/public/card/:uuid/field/:field-id/search/:search-field-id](#get-apipubliccarduuidfieldfield-idsearchsearch-field-id)
- [GET /api/public/card/:uuid/field/:field-id/values](#get-apipubliccarduuidfieldfield-idvalues)
- [GET /api/public/card/:uuid/query](#get-apipubliccarduuidquery)
- [GET /api/public/card/:uuid/query/:export-format](#get-apipubliccarduuidqueryexport-format)
- [GET /api/public/dashboard/:uuid](#get-apipublicdashboarduuid)
- [GET /api/public/dashboard/:uuid/card/:card-id](#get-apipublicdashboarduuidcardcard-id)
- [GET /api/public/dashboard/:uuid/field/:field-id/remapping/:remapped-id](#get-apipublicdashboarduuidfieldfield-idremappingremapped-id)
- [GET /api/public/dashboard/:uuid/field/:field-id/search/:search-field-id](#get-apipublicdashboarduuidfieldfield-idsearchsearch-field-id)
- [GET /api/public/dashboard/:uuid/field/:field-id/values](#get-apipublicdashboarduuidfieldfield-idvalues)
- [GET /api/public/dashboard/:uuid/params/:param-key/search/:query](#get-apipublicdashboarduuidparamsparam-keysearchquery)
- [GET /api/public/dashboard/:uuid/params/:param-key/values](#get-apipublicdashboarduuidparamsparam-keyvalues)
- [GET /api/public/oembed](#get-apipublicoembed)
- [GET /api/public/pivot/card/:uuid/query](#get-apipublicpivotcarduuidquery)
- [GET /api/public/pivot/dashboard/:uuid/card/:card-id](#get-apipublicpivotdashboarduuidcardcard-id)
### `GET /api/public/card/:uuid`
Fetch a publicly-accessible Card an return query results as well as `:card` information. Does not require auth
credentials. Public sharing must be enabled.
......@@ -2168,8 +2341,7 @@ Fetch a publicly-accessible Card an return query results as well as `:card` info
* **`uuid`**
## `GET /api/public/card/:uuid/field/:field-id/remapping/:remapped-id`
### `GET /api/public/card/:uuid/field/:field-id/remapping/:remapped-id`
Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:remapped-id`, but for use with public
Cards.
......@@ -2184,8 +2356,7 @@ Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:
* **`value`** value must be a non-blank string.
## `GET /api/public/card/:uuid/field/:field-id/search/:search-field-id`
### `GET /api/public/card/:uuid/field/:field-id/search/:search-field-id`
Search for values of a Field that is referenced by a public Card.
......@@ -2201,8 +2372,7 @@ Search for values of a Field that is referenced by a public Card.
* **`limit`** value may be nil, or if non-nil, value must be a valid integer greater than zero.
## `GET /api/public/card/:uuid/field/:field-id/values`
### `GET /api/public/card/:uuid/field/:field-id/values`
Fetch FieldValues for a Field that is referenced by a public Card.
......@@ -2212,8 +2382,7 @@ Fetch FieldValues for a Field that is referenced by a public Card.
* **`field-id`**
## `GET /api/public/card/:uuid/query`
### `GET /api/public/card/:uuid/query`
Fetch a publicly-accessible Card an return query results as well as `:card` information. Does not require auth
credentials. Public sharing must be enabled.
......@@ -2224,8 +2393,7 @@ Fetch a publicly-accessible Card an return query results as well as `:card` info
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `GET /api/public/card/:uuid/query/:export-format`
### `GET /api/public/card/:uuid/query/:export-format`
Fetch a publicly-accessible Card and return query results in the specified format. Does not require auth
credentials. Public sharing must be enabled.
......@@ -2238,8 +2406,7 @@ Fetch a publicly-accessible Card and return query results in the specified forma
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `GET /api/public/dashboard/:uuid`
### `GET /api/public/dashboard/:uuid`
Fetch a publicly-accessible Dashboard. Does not require auth credentials. Public sharing must be enabled.
......@@ -2247,8 +2414,7 @@ Fetch a publicly-accessible Dashboard. Does not require auth credentials. Public
* **`uuid`**
## `GET /api/public/dashboard/:uuid/card/:card-id`
### `GET /api/public/dashboard/:uuid/card/:card-id`
Fetch the results for a Card in a publicly-accessible Dashboard. Does not require auth credentials. Public
sharing must be enabled.
......@@ -2261,8 +2427,7 @@ Fetch the results for a Card in a publicly-accessible Dashboard. Does not requir
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `GET /api/public/dashboard/:uuid/field/:field-id/remapping/:remapped-id`
### `GET /api/public/dashboard/:uuid/field/:field-id/remapping/:remapped-id`
Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:remapped-id`, but for use with public
Dashboards.
......@@ -2277,8 +2442,7 @@ Fetch remapped Field values. This is the same as `GET /api/field/:id/remapping/:
* **`value`** value must be a non-blank string.
## `GET /api/public/dashboard/:uuid/field/:field-id/search/:search-field-id`
### `GET /api/public/dashboard/:uuid/field/:field-id/search/:search-field-id`
Search for values of a Field that is referenced by a Card in a public Dashboard.
......@@ -2294,8 +2458,7 @@ Search for values of a Field that is referenced by a Card in a public Dashboard.
* **`limit`** value may be nil, or if non-nil, value must be a valid integer greater than zero.
## `GET /api/public/dashboard/:uuid/field/:field-id/values`
### `GET /api/public/dashboard/:uuid/field/:field-id/values`
Fetch FieldValues for a Field that is referenced by a Card in a public Dashboard.
......@@ -2305,8 +2468,7 @@ Fetch FieldValues for a Field that is referenced by a Card in a public Dashboard
* **`field-id`**
## `GET /api/public/dashboard/:uuid/params/:param-key/search/:query`
### `GET /api/public/dashboard/:uuid/params/:param-key/search/:query`
Fetch filter values for dashboard parameter `param-key`, containing specified `query`.
......@@ -2320,8 +2482,7 @@ Fetch filter values for dashboard parameter `param-key`, containing specified `q
* **`query-params`**
## `GET /api/public/dashboard/:uuid/params/:param-key/values`
### `GET /api/public/dashboard/:uuid/params/:param-key/values`
Fetch filter values for dashboard parameter `param-key`.
......@@ -2333,8 +2494,7 @@ Fetch filter values for dashboard parameter `param-key`.
* **`query-params`**
## `GET /api/public/oembed`
### `GET /api/public/oembed`
oEmbed endpoint used to retreive embed code and metadata for a (public) Metabase URL.
......@@ -2348,8 +2508,7 @@ oEmbed endpoint used to retreive embed code and metadata for a (public) Metabase
* **`maxwidth`** value may be nil, or if non-nil, value must be a valid integer.
## `GET /api/public/pivot/card/:uuid/query`
### `GET /api/public/pivot/card/:uuid/query`
Fetch a publicly-accessible Card an return query results as well as `:card` information. Does not require auth
credentials. Public sharing must be enabled.
......@@ -2360,8 +2519,7 @@ Fetch a publicly-accessible Card an return query results as well as `:card` info
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `GET /api/public/pivot/dashboard/:uuid/card/:card-id`
### `GET /api/public/pivot/dashboard/:uuid/card/:card-id`
Fetch the results for a Card in a publicly-accessible Dashboard. Does not require auth credentials. Public
sharing must be enabled.
......@@ -2375,16 +2533,31 @@ Fetch the results for a Card in a publicly-accessible Dashboard. Does not requir
* **`parameters`** value may be nil, or if non-nil, value must be a valid JSON string.
## `DELETE /api/pulse/:id`
## Pulse
/api/pulse endpoints.
- [DELETE /api/pulse/:id](#delete-apipulseid)
- [DELETE /api/pulse/:id/subscription/email](#delete-apipulseidsubscriptionemail)
- [GET /api/pulse/](#get-apipulse)
- [GET /api/pulse/:id](#get-apipulseid)
- [GET /api/pulse/form_input](#get-apipulseforminput)
- [GET /api/pulse/preview_card/:id](#get-apipulsepreviewcardid)
- [GET /api/pulse/preview_card_info/:id](#get-apipulsepreviewcardinfoid)
- [GET /api/pulse/preview_card_png/:id](#get-apipulsepreviewcardpngid)
- [POST /api/pulse/](#post-apipulse)
- [POST /api/pulse/test](#post-apipulsetest)
- [PUT /api/pulse/:id](#put-apipulseid)
Delete a Pulse. (DEPRECATED -- don't delete a Pulse anymore -- archive it instead.)
### `DELETE /api/pulse/:id`
Delete a Pulse. (DEPRECATED -- don't delete a Pulse anymore -- archive it instead.).
##### PARAMS:
* **`id`**
## `DELETE /api/pulse/:id/subscription/email`
### `DELETE /api/pulse/:id/subscription/email`
For users to unsubscribe themselves from a pulse subscription.
......@@ -2392,10 +2565,11 @@ For users to unsubscribe themselves from a pulse subscription.
* **`id`**
### `GET /api/pulse/`
## `GET /api/pulse/`
Fetch all Pulses
Fetch all Pulses. If `dashboard_id` is specified, restricts results to dashboard subscriptions
associated with that dashboard. If `user_id` is specified, restricts results to pulses or subscriptions
created by the user, or for which the user is a known recipient.
##### PARAMS:
......@@ -2403,8 +2577,9 @@ Fetch all Pulses
* **`dashboard_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
* **`user_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `GET /api/pulse/:id`
### `GET /api/pulse/:id`
Fetch `Pulse` with ID.
......@@ -2412,13 +2587,11 @@ Fetch `Pulse` with ID.
* **`id`**
## `GET /api/pulse/form_input`
### `GET /api/pulse/form_input`
Provides relevant configuration information and user choices for creating/updating Pulses.
## `GET /api/pulse/preview_card/:id`
### `GET /api/pulse/preview_card/:id`
Get HTML rendering of a Card with `id`.
......@@ -2426,8 +2599,7 @@ Get HTML rendering of a Card with `id`.
* **`id`**
## `GET /api/pulse/preview_card_info/:id`
### `GET /api/pulse/preview_card_info/:id`
Get JSON object containing HTML rendering of a Card with `id` and other information.
......@@ -2435,8 +2607,7 @@ Get JSON object containing HTML rendering of a Card with `id` and other informat
* **`id`**
## `GET /api/pulse/preview_card_png/:id`
### `GET /api/pulse/preview_card_png/:id`
Get PNG rendering of a Card with `id`.
......@@ -2444,8 +2615,7 @@ Get PNG rendering of a Card with `id`.
* **`id`**
## `POST /api/pulse/`
### `POST /api/pulse/`
Create a new `Pulse`.
......@@ -2467,8 +2637,7 @@ Create a new `Pulse`.
* **`parameters`** value must be an array. Each value must be a map.
## `POST /api/pulse/test`
### `POST /api/pulse/test`
Test send an unsaved pulse.
......@@ -2488,8 +2657,7 @@ Test send an unsaved pulse.
* **`dashboard_id`** value may be nil, or if non-nil, value must be an integer greater than zero.
## `PUT /api/pulse/:id`
### `PUT /api/pulse/:id`
Update a Pulse with `id`.
......@@ -2514,7 +2682,12 @@ Update a Pulse with `id`.
* **`pulse-updates`**
## `GET /api/revision/`
## Revision
- [GET /api/revision/](#get-apirevision)
- [POST /api/revision/revert](#post-apirevisionrevert)
### `GET /api/revision/`
Get revisions of an object.
......@@ -2524,8 +2697,7 @@ Get revisions of an object.
* **`id`** value must be an integer.
## `POST /api/revision/revert`
### `POST /api/revision/revert`
Revert an object to a prior revision.
......@@ -2538,7 +2710,12 @@ Revert an object to a prior revision.
* **`revision_id`** value must be an integer.
## `GET /api/search/`
## Search
- [GET /api/search/](#get-apisearch)
- [GET /api/search/models](#get-apisearchmodels)
### `GET /api/search/`
Search within a bunch of models for the substring `q`.
For the list of models, check `metabase.search.config/searchable-models.
......@@ -2548,7 +2725,7 @@ Search within a bunch of models for the substring `q`.
pass in a DB id value to `table_db_id`.
To specify a list of models, pass in an array to `models`.
.
##### PARAMS:
......@@ -2560,10 +2737,9 @@ Search within a bunch of models for the substring `q`.
* **`models`** value may be nil, or if non-nil, value must satisfy one of the following requirements: 1) value must be an array. Each value must be a non-blank string. 2) value must be a non-blank string.
### `GET /api/search/models`
## `GET /api/search/models`
Get the set of models that a search query will return
Get the set of models that a search query will return.
##### PARAMS:
......@@ -2574,9 +2750,22 @@ Get the set of models that a search query will return
* **`table-db-id`**
## `DELETE /api/segment/:id`
## Segment
/api/segment endpoints.
- [DELETE /api/segment/:id](#delete-apisegmentid)
- [GET /api/segment/](#get-apisegment)
- [GET /api/segment/:id](#get-apisegmentid)
- [GET /api/segment/:id/related](#get-apisegmentidrelated)
- [GET /api/segment/:id/revisions](#get-apisegmentidrevisions)
- [POST /api/segment/](#post-apisegment)
- [POST /api/segment/:id/revert](#post-apisegmentidrevert)
- [PUT /api/segment/:id](#put-apisegmentid)
### `DELETE /api/segment/:id`
Archive a Segment. (DEPRECATED -- Just pass updated value of `:archived` to the `PUT` endpoint instead.)
Archive a Segment. (DEPRECATED -- Just pass updated value of `:archived` to the `PUT` endpoint instead.).
##### PARAMS:
......@@ -2584,13 +2773,11 @@ Archive a Segment. (DEPRECATED -- Just pass updated value of `:archived` to the
* **`revision_message`** value must be a non-blank string.
## `GET /api/segment/`
### `GET /api/segment/`
Fetch *all* `Segments`.
## `GET /api/segment/:id`
### `GET /api/segment/:id`
Fetch `Segment` with ID.
......@@ -2598,8 +2785,7 @@ Fetch `Segment` with ID.
* **`id`**
## `GET /api/segment/:id/related`
### `GET /api/segment/:id/related`
Return related entities.
......@@ -2607,8 +2793,7 @@ Return related entities.
* **`id`**
## `GET /api/segment/:id/revisions`
### `GET /api/segment/:id/revisions`
Fetch `Revisions` for `Segment` with ID.
......@@ -2616,8 +2801,7 @@ Fetch `Revisions` for `Segment` with ID.
* **`id`**
## `POST /api/segment/`
### `POST /api/segment/`
Create a new `Segment`.
......@@ -2631,8 +2815,7 @@ Create a new `Segment`.
* **`definition`** value must be a map.
## `POST /api/segment/:id/revert`
### `POST /api/segment/:id/revert`
Revert a `Segement` to a prior `Revision`.
......@@ -2642,8 +2825,7 @@ Revert a `Segement` to a prior `Revision`.
* **`revision_id`** value must be an integer greater than zero.
## `PUT /api/segment/:id`
### `PUT /api/segment/:id`
Update a `Segment` with ID.
......@@ -2668,7 +2850,19 @@ Update a `Segment` with ID.
* **`id`**
## `DELETE /api/session/`
## Session
/api/session endpoints.
- [DELETE /api/session/](#delete-apisession)
- [GET /api/session/password_reset_token_valid](#get-apisessionpasswordresettokenvalid)
- [GET /api/session/properties](#get-apisessionproperties)
- [POST /api/session/](#post-apisession)
- [POST /api/session/forgot_password](#post-apisessionforgotpassword)
- [POST /api/session/google_auth](#post-apisessiongoogleauth)
- [POST /api/session/reset_password](#post-apisessionresetpassword)
### `DELETE /api/session/`
Logout.
......@@ -2676,8 +2870,7 @@ Logout.
* **`metabase-session-id`**
## `GET /api/session/password_reset_token_valid`
### `GET /api/session/password_reset_token_valid`
Check is a password reset token is valid and isn't expired.
......@@ -2685,13 +2878,11 @@ Check is a password reset token is valid and isn't expired.
* **`token`** value must be a string.
## `GET /api/session/properties`
### `GET /api/session/properties`
Get all global properties and their values. These are the specific `Settings` which are meant to be public.
## `POST /api/session/`
### `POST /api/session/`
Login.
......@@ -2703,8 +2894,7 @@ Login.
* **`request`**
## `POST /api/session/forgot_password`
### `POST /api/session/forgot_password`
Send a reset email when user has forgotten their password.
......@@ -2716,8 +2906,7 @@ Send a reset email when user has forgotten their password.
* **`request`**
## `POST /api/session/google_auth`
### `POST /api/session/google_auth`
Login with Google Auth.
......@@ -2727,8 +2916,7 @@ Login with Google Auth.
* **`request`**
## `POST /api/session/reset_password`
### `POST /api/session/reset_password`
Reset password with a reset token.
......@@ -2741,14 +2929,22 @@ Reset password with a reset token.
* **`request`**
## `GET /api/setting/`
## Setting
/api/setting endpoints.
- [GET /api/setting/](#get-apisetting)
- [GET /api/setting/:key](#get-apisettingkey)
- [PUT /api/setting/](#put-apisetting)
- [PUT /api/setting/:key](#put-apisettingkey)
### `GET /api/setting/`
Get all `Settings` and their values. You must be a superuser to do this.
You must be a superuser to do this.
## `GET /api/setting/:key`
### `GET /api/setting/:key`
Fetch a single `Setting`. You must be a superuser to do this.
......@@ -2758,8 +2954,7 @@ You must be a superuser to do this.
* **`key`** value must be a non-blank string.
## `PUT /api/setting/`
### `PUT /api/setting/`
Update multiple `Settings` values. You must be a superuser to do this.
......@@ -2769,8 +2964,7 @@ You must be a superuser to do this.
* **`settings`**
## `PUT /api/setting/:key`
### `PUT /api/setting/:key`
Create/update a `Setting`. You must be a superuser to do this.
This endpoint can also be used to delete Settings by passing `nil` for `:value`.
......@@ -2784,14 +2978,19 @@ You must be a superuser to do this.
* **`value`**
## `GET /api/setup/admin_checklist`
## Setup
Return various "admin checklist" steps and whether they've been completed. You must be a superuser to see this!
- [GET /api/setup/admin_checklist](#get-apisetupadminchecklist)
- [POST /api/setup/](#post-apisetup)
- [POST /api/setup/validate](#post-apisetupvalidate)
You must be a superuser to do this.
### `GET /api/setup/admin_checklist`
Return various "admin checklist" steps and whether they've been completed. You must be a superuser to see this!.
You must be a superuser to do this.
## `POST /api/setup/`
### `POST /api/setup/`
Special endpoint for creating the first user during setup. This endpoint both creates the user AND logs them in and
returns a session ID.
......@@ -2832,8 +3031,7 @@ Special endpoint for creating the first user during setup. This endpoint both cr
* **`last_name`** value must be a non-blank string.
## `POST /api/setup/validate`
### `POST /api/setup/validate`
Validate that we can connect to a database given a set of details.
......@@ -2846,7 +3044,13 @@ Validate that we can connect to a database given a set of details.
* **`token`** Token does not match the setup token.
## `PUT /api/slack/settings`
## Slack
/api/slack endpoints.
- [PUT /api/slack/settings](#put-apislacksettings)
### `PUT /api/slack/settings`
Update Slack related settings. You must be a superuser to do this.
......@@ -2861,12 +3065,28 @@ You must be a superuser to do this.
* **`slack-settings`**
## `GET /api/table/`
## Table
Get all `Tables`.
/api/table endpoints.
- [GET /api/table/](#get-apitable)
- [GET /api/table/:id](#get-apitableid)
- [GET /api/table/:id/fks](#get-apitableidfks)
- [GET /api/table/:id/query_metadata](#get-apitableidquerymetadata)
- [GET /api/table/:id/related](#get-apitableidrelated)
- [GET /api/table/card__:id/fks](#get-apitablecardidfks)
- [GET /api/table/card__:id/query_metadata](#get-apitablecardidquerymetadata)
- [POST /api/table/:id/discard_values](#post-apitableiddiscardvalues)
- [POST /api/table/:id/rescan_values](#post-apitableidrescanvalues)
- [PUT /api/table/](#put-apitable)
- [PUT /api/table/:id](#put-apitableid)
- [PUT /api/table/:id/fields/order](#put-apitableidfieldsorder)
## `GET /api/table/:id`
### `GET /api/table/`
Get all `Tables`.
### `GET /api/table/:id`
Get `Table` with ID.
......@@ -2874,8 +3094,7 @@ Get `Table` with ID.
* **`id`**
## `GET /api/table/:id/fks`
### `GET /api/table/:id/fks`
Get all foreign keys whose destination is a `Field` that belongs to this `Table`.
......@@ -2883,8 +3102,7 @@ Get all foreign keys whose destination is a `Field` that belongs to this `Table`
* **`id`**
## `GET /api/table/:id/query_metadata`
### `GET /api/table/:id/query_metadata`
Get metadata about a `Table` useful for running queries.
Returns DB, fields, field FKs, and field values.
......@@ -2902,8 +3120,7 @@ Get metadata about a `Table` useful for running queries.
* **`include_hidden_fields`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
## `GET /api/table/:id/related`
### `GET /api/table/:id/related`
Return related entities.
......@@ -2911,14 +3128,12 @@ Return related entities.
* **`id`**
## `GET /api/table/card__:id/fks`
### `GET /api/table/card__:id/fks`
Return FK info for the 'virtual' table for a Card. This is always empty, so this endpoint
serves mainly as a placeholder to avoid having to change anything on the frontend.
## `GET /api/table/card__:id/query_metadata`
### `GET /api/table/card__:id/query_metadata`
Return metadata for the 'virtual' table for a Card.
......@@ -2926,8 +3141,7 @@ Return metadata for the 'virtual' table for a Card.
* **`id`**
## `POST /api/table/:id/discard_values`
### `POST /api/table/:id/discard_values`
Discard the FieldValues belonging to the Fields in this Table. Only applies to fields that have FieldValues. If
this Table's Database is set up to automatically sync FieldValues, they will be recreated during the next cycle.
......@@ -2938,8 +3152,7 @@ You must be a superuser to do this.
* **`id`**
## `POST /api/table/:id/rescan_values`
### `POST /api/table/:id/rescan_values`
Manually trigger an update for the FieldValues for the Fields belonging to this Table. Only applies to Fields that
are eligible for FieldValues.
......@@ -2950,8 +3163,7 @@ You must be a superuser to do this.
* **`id`**
## `PUT /api/table/`
### `PUT /api/table/`
Update all `Table` in `ids`.
......@@ -2973,8 +3185,7 @@ Update all `Table` in `ids`.
* **`show_in_getting_started`** value may be nil, or if non-nil, value must be a boolean.
## `PUT /api/table/:id`
### `PUT /api/table/:id`
Update `Table` with ID.
......@@ -2998,10 +3209,9 @@ Update `Table` with ID.
* **`id`**
### `PUT /api/table/:id/fields/order`
## `PUT /api/table/:id/fields/order`
Reorder fields
Reorder fields.
You must be a superuser to do this.
......@@ -3012,14 +3222,21 @@ You must be a superuser to do this.
* **`field_order`** value must be an array. Each value must be an integer greater than zero.
## `GET /api/task/`
## Task
Fetch a list of recent tasks stored as Task History
/api/task endpoints.
You must be a superuser to do this.
- [GET /api/task/](#get-apitask)
- [GET /api/task/:id](#get-apitaskid)
- [GET /api/task/info](#get-apitaskinfo)
### `GET /api/task/`
## `GET /api/task/:id`
Fetch a list of recent tasks stored as Task History.
You must be a superuser to do this.
### `GET /api/task/:id`
Get `TaskHistory` entry with ID.
......@@ -3027,15 +3244,20 @@ Get `TaskHistory` entry with ID.
* **`id`**
## `GET /api/task/info`
### `GET /api/task/info`
Return raw data about all scheduled tasks (i.e., Quartz Jobs and Triggers).
You must be a superuser to do this.
## `GET /api/tiles/:zoom/:x/:y/:lat-field-id/:lon-field-id/:lat-col-idx/:lon-col-idx/`
## Tiles
`/api/tiles` endpoints.
- [GET /api/tiles/:zoom/:x/:y/:lat-field-id/:lon-field-id/:lat-col-idx/:lon-col-idx/](#get-apitileszoomxylat-field-idlon-field-idlat-col-idxlon-col-idx)
### `GET /api/tiles/:zoom/:x/:y/:lat-field-id/:lon-field-id/:lat-col-idx/:lon-col-idx/`
This endpoints provides an image with the appropriate pins rendered given a MBQL `query` (passed as a GET query
string param). We evaluate the query and find the set of lat/lon pairs which are relevant and then render the
......@@ -3061,9 +3283,13 @@ This endpoints provides an image with the appropriate pins rendered given a MBQL
* **`query`** value must be a valid JSON string.
## `GET /api/transform/:db-id/:schema/:transform-name`
## Transform
- [GET /api/transform/:db-id/:schema/:transform-name](#get-apitransformdb-idschematransform-name)
Look up a database schema transform
### `GET /api/transform/:db-id/:schema/:transform-name`
Look up a database schema transform.
##### PARAMS:
......@@ -3074,7 +3300,22 @@ Look up a database schema transform
* **`transform-name`**
## `DELETE /api/user/:id`
## User
/api/user endpoints.
- [DELETE /api/user/:id](#delete-apiuserid)
- [GET /api/user/](#get-apiuser)
- [GET /api/user/:id](#get-apiuserid)
- [GET /api/user/current](#get-apiusercurrent)
- [POST /api/user/](#post-apiuser)
- [POST /api/user/:id/send_invite](#post-apiuseridsendinvite)
- [PUT /api/user/:id](#put-apiuserid)
- [PUT /api/user/:id/password](#put-apiuseridpassword)
- [PUT /api/user/:id/qbnewb](#put-apiuseridqbnewb)
- [PUT /api/user/:id/reactivate](#put-apiuseridreactivate)
### `DELETE /api/user/:id`
Disable a `User`. This does not remove the `User` from the DB, but instead disables their account.
......@@ -3084,8 +3325,7 @@ You must be a superuser to do this.
* **`id`**
## `GET /api/user/`
### `GET /api/user/`
Fetch a list of `Users`. By default returns every active user but only active users.
......@@ -3110,8 +3350,7 @@ Fetch a list of `Users`. By default returns every active user but only active us
* **`include_deactivated`** value may be nil, or if non-nil, value must be a valid boolean string ('true' or 'false').
## `GET /api/user/:id`
### `GET /api/user/:id`
Fetch a `User`. You must be fetching yourself *or* be a superuser.
......@@ -3119,15 +3358,13 @@ Fetch a `User`. You must be fetching yourself *or* be a superuser.
* **`id`**
## `GET /api/user/current`
### `GET /api/user/current`
Fetch the current `User`.
### `POST /api/user/`
## `POST /api/user/`
Create a new `User`, return a 400 if the email address is already taken
Create a new `User`, return a 400 if the email address is already taken.
You must be a superuser to do this.
......@@ -3145,8 +3382,7 @@ You must be a superuser to do this.
* **`login_attributes`** value may be nil, or if non-nil, login attribute keys must be a keyword or string
## `POST /api/user/:id/send_invite`
### `POST /api/user/:id/send_invite`
Resend the user invite email for a given user.
......@@ -3156,8 +3392,7 @@ You must be a superuser to do this.
* **`id`**
## `PUT /api/user/:id`
### `PUT /api/user/:id`
Update an existing, active `User`.
......@@ -3179,8 +3414,7 @@ Update an existing, active `User`.
* **`locale`** value may be nil, or if non-nil, String must be a valid two-letter ISO language or language-country code e.g. en or en_US.
## `PUT /api/user/:id/password`
### `PUT /api/user/:id/password`
Update a user's password.
......@@ -3192,8 +3426,7 @@ Update a user's password.
* **`old_password`**
## `PUT /api/user/:id/qbnewb`
### `PUT /api/user/:id/qbnewb`
Indicate that a user has been informed about the vast intricacies of 'the' Query Builder.
......@@ -3201,10 +3434,9 @@ Indicate that a user has been informed about the vast intricacies of 'the' Query
* **`id`**
### `PUT /api/user/:id/reactivate`
## `PUT /api/user/:id/reactivate`
Reactivate user at `:id`
Reactivate user at `:id`.
You must be a superuser to do this.
......@@ -3213,42 +3445,49 @@ You must be a superuser to do this.
* **`id`**
## `GET /api/util/bug_report_details`
## Util
Random utilty endpoints for things that don't belong anywhere else in particular, e.g. endpoints for certain admin
page tasks.
- [GET /api/util/bug_report_details](#get-apiutilbugreportdetails)
- [GET /api/util/diagnostic_info/connection_pool_info](#get-apiutildiagnosticinfoconnectionpoolinfo)
- [GET /api/util/logs](#get-apiutillogs)
- [GET /api/util/random_token](#get-apiutilrandomtoken)
- [GET /api/util/stats](#get-apiutilstats)
- [POST /api/util/password_check](#post-apiutilpasswordcheck)
### `GET /api/util/bug_report_details`
Returns version and system information relevant to filing a bug report against Metabase.
You must be a superuser to do this.
## `GET /api/util/diagnostic_info/connection_pool_info`
### `GET /api/util/diagnostic_info/connection_pool_info`
Returns database connection pool info for the current Metabase instance.
You must be a superuser to do this.
## `GET /api/util/logs`
### `GET /api/util/logs`
Logs.
You must be a superuser to do this.
## `GET /api/util/random_token`
### `GET /api/util/random_token`
Return a cryptographically secure random 32-byte token, encoded as a hexadecimal string.
Intended for use when creating a value for `embedding-secret-key`.
## `GET /api/util/stats`
### `GET /api/util/stats`
Anonymous usage stats. Endpoint for testing, and eventually exposing this to instance admins to let them see
what is being phoned home.
You must be a superuser to do this.
## `POST /api/util/password_check`
### `POST /api/util/password_check`
Endpoint that checks if the supplied password meets the currently configured password complexity rules.
......
src/metabase/api/common/internal.clj
+ 4
− 4
View file @ bd53aed6
......@@ -62,7 +62,7 @@
(log/warn
(u/format-color 'red (str "We don't have a nice error message for schema: %s defined at %s\n"
"Consider wrapping it in `su/with-api-error-message`.")
(u/pprint-to-str schema) route-str))))))
(u/pprint-to-str schema) (u/add-period route-str)))))))
(defn- param-name
"Return the appropriate name for this `param-symb` based on its `schema`. Usually this is just the name of the
......@@ -84,9 +84,9 @@
(defn- format-route-dox
"Return a markdown-formatted string to be used as documentation for a `defendpoint` function."
[route-str docstr param->schema]
(str (format "## `%s`" route-str)
(str (format "### `%s`" route-str)
(when (seq docstr)
(str "\n\n" docstr))
(str "\n\n" (u/add-period docstr)))
(format-route-schema-dox param->schema route-str)))
(defn- contains-superuser-check?
......@@ -100,7 +100,7 @@
"Generate a documentation string for a `defendpoint` route."
[method route docstr args param->schema body]
(format-route-dox (endpoint-name method route)
(str docstr (when (contains-superuser-check? body)
(str (u/add-period docstr) (when (contains-superuser-check? body)
"\n\nYou must be a superuser to do this."))
(merge (args-form-symbols args)
param->schema)))
......
src/metabase/cmd/endpoint_dox.clj
+ 112
− 13
View file @ bd53aed6
......@@ -5,22 +5,121 @@
[metabase.plugins.classloader :as classloader]
[metabase.util :as u]))
;;;; API docs intro
(defn- api-docs-intro
"Exists just so we can write the intro in Markdown."
[]
(str (slurp "src/metabase/cmd/resources/api-intro.md") "\n\n"))
;;;; API docs section title
(defn- endpoint-ns-name
"Creates a name for endpoints in a namespace, like all the endpoints for Alerts."
[endpoint]
(->> (:ns endpoint)
ns-name
name
(#(str/split % #"\."))
last
str/capitalize))
(defn- section-title
"Creates a section title for a set of endpoints."
[ep-title]
(str/replace (str "## " ep-title "\n\n") #"-" " "))
;;;; API docs section description
(defn- section-description
"If there is a namespace docstring, include the docstring with a paragraph break."
[ep-data]
(let [desc (u/add-period (:doc (meta (:ns (first ep-data)))))]
(if (str/blank? desc)
desc
(str desc "\n\n"))))
;;;; API docs section table of contents
(defn- anchor-link
"Converts an endpoint string to an anchor link, like [GET /api/alert](#get-apialert),
for use in section tables of contents."
[ep-name]
(let [al (-> (str "#" (str/lower-case ep-name))
(str/replace #"[/:-_]" "")
(str/replace " " "-")
(#(str "(" % ")")))]
(str "[" ep-name "]" al)))
(defn- toc-links
"Creates a list of links to endpoints in the relevant namespace."
[endpoint]
(-> (:endpoint-str endpoint)
(str/replace #"[#+`]" "")
str/trim
anchor-link
(#(str " - " %))))
(defn section-toc
"Generates a table of contents for endpoints in a section."
[ep-data]
(str (str/join "\n" (map toc-links ep-data)) "\n\n"))
;;;; API docs section endpoints
(defn- endpoint-str
"Creates a name for an endpoint: VERB /path/to/endpoint. Used to build anchor links in the table of contents."
[endpoint]
(-> (:doc endpoint)
(str/split #"\n")
first
str/trim))
(defn- process-endpoint
"Decorates endpoints with strings for building api endpoint sections."
[endpoint]
(assoc endpoint
:endpoint-str (endpoint-str endpoint)
:ns-name (endpoint-ns-name endpoint)))
(defn- collect-endpoints
"Gets a list of all API endpoints. Currently excludes Enterprise endpoints."
[]
(for [ns-symb u/metabase-namespace-symbols
:when (str/includes? (name ns-symb) "metabase.api")
[symb varr] (do (classloader/require ns-symb)
(sort (ns-interns ns-symb)))
:when (:is-endpoint? (meta varr))]
(meta varr)))
(defn- section-endpoints
"Builds a list of endpoints and their parameters. Relies on docstring generation in /api/common/internal.clj."
[ep-data]
(str/join "\n\n" (map :doc ep-data)))
;;;; Generate API sections
(defn endpoint-section
"Builds a section with the name, description, table of contents for endpoints in a namespace,
followed by the endpoint and their parameter descriptions."
[ep-map]
(for [[ep ep-data] ep-map]
(apply str
(section-title ep)
(section-description ep-data)
(section-toc ep-data)
(section-endpoints ep-data))))
(defn- dox
"Generate a Markdown string containing documentation for all Metabase API endpoints."
[]
(str "# API Documentation for Metabase"
"\n\n"
"_This file was generated from source comments by `clojure -M:run api-documentation`_."
"\n\n"
"Check out an introduction to the "
"[Metabase API](https://www.metabase.com/learn/developing-applications/advanced-metabase/metabase-api.html)."
"\n\n"
(str/join "\n\n\n" (for [ns-symb u/metabase-namespace-symbols
:when (.startsWith (name ns-symb) "metabase.api.")
[symb varr] (do (classloader/require ns-symb)
(sort (ns-interns ns-symb)))
:when (:is-endpoint? (meta varr))]
(:doc (meta varr))))))
(str (api-docs-intro)
(str/join "\n\n\n"
(->> (collect-endpoints)
(map process-endpoint)
(group-by :ns-name)
(into (sorted-map))
endpoint-section))))
(defn generate-dox!
"Write markdown file containing documentation for all the API endpoints to `docs/api-documentation.md`."
......
src/metabase/cmd/resources/api-intro.md 0 → 100644
+ 5
− 0
View file @ bd53aed6
# API Documentation for Metabase
_This file was generated from source comments by `clojure -M:run api-documentation`_.
Check out an introduction to the [Metabase API](https://www.metabase.com/learn/administration/metabase-api.html).
src/metabase/util.clj
+ 8
− 0
View file @ bd53aed6
......@@ -31,6 +31,14 @@
[shared.u
qualified-name])
(defn add-period
"Fixes strings that don't terminate in a period."
[s]
(if (or (str/blank? s)
(#{\. \? \!} (last s)))
s
(str s ".")))
(defn lower-case-en
"Locale-agnostic version of `clojure.string/lower-case`.
`clojure.string/lower-case` uses the default locale in conversions, turning
......
test/metabase/cmd/endpoint_dox_test.clj 0 → 100644
+ 30
− 0
View file @ bd53aed6
(ns metabase.cmd.endpoint-dox-test
(:require [clojure.test :refer :all]
[metabase.cmd.endpoint-dox :as endpoint-dox]))
(def endpoints {"Activity"
[{:ns (find-ns 'metabase.api.activity),
:name "GET_",
:file "metabase/api/activity.clj",
:ns-name "Activity",
:column 1,
:is-endpoint? true,
:line 61,
:endpoint-str "### `GET /api/activity/`",
:doc "### `GET /api/activity/`\n\nGet recent activity."}
{:ns (find-ns 'metabase.api.activity),
:name "GET_recent_views",
:file "metabase/api/activity.clj",
:ns-name "Activity",
:column 1,
:is-endpoint? true,
:line 76,
:endpoint-str "### `GET /api/activity/recent_views`",
:doc
"### `GET /api/activity/recent_views`\n\nGet the list of 10 things the current user has been viewing most recently."}]})
(def section-markdown "## Activity\n\n - [GET /api/activity/](#get-apiactivity)\n - [GET /api/activity/recent_views](#get-apiactivityrecentviews)\n\n### `GET /api/activity/`\n\nGet recent activity.\n\n### `GET /api/activity/recent_views`\n\nGet the list of 10 things the current user has been viewing most recently.")
(deftest endpoint-section-test
(is (= (first (endpoint-dox/endpoint-section endpoints))
section-markdown)))
test/metabase/util/schema_test.clj
+ 1
− 1
View file @ bd53aed6
......@@ -23,7 +23,7 @@
(deftest api-param-test
(testing "check that API error message respects `api-param` when specified"
(is (= (str "## `POST metabase.util.schema-test/:id/dimension`\n"
(is (= (str "### `POST metabase.util.schema-test/:id/dimension`\n"
"\n"
"Sets the dimension for the given object with ID.\n"
"\n"
......
test/metabase/util_test.clj
+ 10
− 0
View file @ bd53aed6
......@@ -8,6 +8,16 @@
[metabase.test :as mt]
[metabase.util :as u]))
(deftest add-period-test
(is (= "This sentence needs a period."
(u/add-period "This sentence needs a period")))
(is (= "This sentence doesn't need a period!"
(u/add-period "This sentence doesn't need a period!")))
(is (= "What about this one?"
(u/add-period "What about this one?")))
(is (= " "
(u/add-period " "))))
(deftest decolorize-test
(is (= "message"
(u/colorize 'red "message")))
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment