What's new in 0.40.0 for Metabase REST API clients

We paginated some API endpoints which needed to be paginated in order to support pagination in the Metabase application. This is a breaking change.

Breaking Changes

• /api/user endpoint is now paginated and it also has search now. It accepts new parameters, all of them optional:

• • query: str. Query to filter on the users. Not a fuzzy search.
• • group_id: int. Group ID to filter on the users.
• • status: str. User status to filter on users. include_deactivated is not deprecated. (We added status so we can get the set of deactivated users only, as opposed to all users.)
• • limit: int. limit for endpoint pagination.
• • offset: int. offset for endpoint pagination.

Only limit and offset pagination is supported at this time.

• /api/user previously returned an array of users. Now it returns an object structured like this:

{
  data: array[object], The user data.
  total: number, The total number of users with respect to the query.\
                 So if you query and get 3 results from your set of 8 users, this will be 3.
  limit: number, limit option passed in. null if limit was not passed in.
  offset: number, offset option passed in. null if offset was not passed in.
}

• /api/database and /api/database endpoints are now paginated. They accept new parameters, all of them optional:

• • limit: int. limit for endpoint pagination.
• • offset: int. offset for endpoint pagination.

Only limit and offset pagination is supported at this time.

• /api/database previously returned an array of databases. Now it returns an object structured like this:

{
  data: array[object], The database data.
  total: number, The total number of database.
  limit: number, limit option passed in. null if limit was not passed in.
  offset: number, offset option passed in. null if offset was not passed in.
}

• /api/search endpoint is now paginated and has some new options to support new functionality in Metabase app. It accepts new parameters, all of them optional:

• • table_db_id: int. When you are querying tables, limits the tables for search results to the db_id given. So if you pass in 3, you only get tables from db_id 3.
• • models: arr. Array of models to limit the query to. This is limited to the searchable-models in metabase.search.config/searchable-models, at time of writing {dashboard metric segment card collection table pulse database}.
• • limit: int. limit for endpoint pagination.
• • offset: int. limit for endpoint pagination.

Note that passing in an array with the GET verb to the API is done like such:

/api/search?q=foo&model=database&model=table

and not in the PHP way, like,

/api/search?q=foo&model[]=database&model[]=table

• /api/search previously returned an array of query results. Now it returns an object structured like this:

{
  data: array[object], Query results.
  total: number, The total number of query elements returned.
  limit: number, limit option passed in. null if limit was not passed in.
  offset: number, offset option passed in. null if offset was not passed in.
  table_db_id: number, table db id option passed in, null if not passed in.
  models: array, models option passed in, null if not passed in.
}

• /api/collection/:id/items and /api/collection/root/items endpoints are now paginated. They accept new parameters, all of them optional:

• • limit: int. limit for endpoint pagination.
• • offset: int. offset for endpoint pagination.

Only limit and offset pagination is supported at this time.

• /api/collection/:id/items and /api/collection/root/items previously returned an array of collection items. Now they return an object structured like this:

{
  data: array[object], The collection item data.
  total: number, The total number of collection items.
  limit: number, limit option passed in. null if limit was not passed in.
  offset: number, offset option passed in. null if offset was not passed in.
  models: array[string] corresponding to models passed in, null if not passed in.
}

The possible set of models is {card collection dashboard pulse snippet}. Default behavior if you pass in no models is equivalent to passing in all models. If you want to explicitly have no models (and want empty results for some reason, as we actually do in one place), passing in no_models will have that behavior.