mirror of
https://github.com/simonw/datasette.git
synced 2026-06-15 13:36:58 +02:00
Clearer examples and descriptions for JSON API extras
Review of the generated ?_extra= documentation found several extras
with no example output or with examples that needed explanation:
- extras: now shows an abbreviated example of the toggle list and has
a clearer description (which also improves the live API output)
- set_column_type_ui: example of the shape seen with set-column-type
permission, plus a note that it is null otherwise
- column_types: live example generated from a table with an assigned
column type instead of an empty {}
- metadata: live table example now demonstrates a table description
and column descriptions; row and query examples gained explanatory
notes
- expandable_columns, foreign_key_tables, facets_timed_out, next_url,
renderers: notes explaining the shape of their output
Also added docs_note cross-references to the relevant documentation:
facets, pagination, render_cell and register_output_renderer plugin
hooks, column type configuration and API, metadata, custom templates,
permissions and foreign key label expansion. foreign_key_tables is
now flagged as potentially executing additional queries.
https://claude.ai/code/session_01EfjBe6E817m9XNFW7EX3Vm
This commit is contained in:
Claude
parent
1d4212122e
commit
9ccdfd8c45
3 changed files with 360 additions and 42 deletions
|
|
@ -276,7 +276,7 @@ The available table extras are listed below.
|
|||
"select count(*) from facetable "
|
||||
|
||||
``facet_results``
|
||||
Results of facets calculated against this data (May execute additional queries.)
|
||||
Results of facets calculated against this data (May execute additional queries. See :ref:`facets` for details of how facets work.)
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_facet=state&_extra=facet_results.
|
||||
|
||||
|
|
@ -309,12 +309,14 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_facet=state&_extra=facets_timed_out``
|
||||
|
||||
A list of the names of any facets that exceeded the :ref:`setting_facet_time_limit_ms` time limit - an empty list if every facet calculation completed.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[]
|
||||
|
||||
``suggested_facets``
|
||||
Suggestions for facets that might return interesting results (May execute additional queries.)
|
||||
Suggestions for facets that might return interesting results (May execute additional queries. Suggestions are controlled by the :ref:`setting_suggest_facets` setting.)
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_extra=suggested_facets.
|
||||
|
||||
|
|
@ -341,6 +343,8 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_size=1&_extra=next_url``
|
||||
|
||||
``null`` if there are no more pages of results. See :ref:`json_api_pagination`.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"http://localhost/fixtures/facetable.json?_size=1&_extra=next_url&_next=1"
|
||||
|
|
@ -426,7 +430,7 @@ The available table extras are listed below.
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item per row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -452,7 +456,7 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=debug``
|
||||
|
||||
|
|
@ -501,28 +505,108 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``column_types``
|
||||
Column type assignments for this table
|
||||
Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
|
||||
|
||||
.. code-block:: json
|
||||
``GET /fixtures/facetable.json?_size=0&_extra=column_types``
|
||||
|
||||
{}
|
||||
|
||||
``set_column_type_ui``
|
||||
Column type UI metadata for this table
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=metadata``
|
||||
This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"columns": {}
|
||||
"tags": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
}
|
||||
}
|
||||
|
||||
``set_column_type_ui``
|
||||
Information needed to build an interface for assigning column types (``null`` unless the current actor is allowed to use the :ref:`set column type API <TableSetColumnTypeView>` for this table.)
|
||||
|
||||
Shape abbreviated to two columns, as seen by an actor with ``set-column-type`` permission. ``current`` is the column type currently assigned to each column and ``options`` lists the types that could be assigned to it.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"path": "/fixtures/facetable/-/set-column-type",
|
||||
"columns": {
|
||||
"created": {
|
||||
"current": null,
|
||||
"options": [
|
||||
{
|
||||
"name": "email",
|
||||
"description": "Email address"
|
||||
},
|
||||
{
|
||||
"name": "json",
|
||||
"description": "JSON data"
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"description": "URL"
|
||||
}
|
||||
]
|
||||
},
|
||||
"tags": {
|
||||
"current": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
},
|
||||
"options": [
|
||||
{
|
||||
"name": "email",
|
||||
"description": "Email address"
|
||||
},
|
||||
{
|
||||
"name": "json",
|
||||
"description": "JSON data"
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"description": "URL"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=metadata``
|
||||
|
||||
This example is from an instance where the ``facetable`` table has a metadata ``description`` and a :ref:`column description <metadata_column_descriptions>` for its ``state`` column. The ``columns`` object is empty for tables with no column descriptions.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"description": "A demo table of places, used to demonstrate facets",
|
||||
"columns": {
|
||||
"state": "Two letter US state code"
|
||||
}
|
||||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -543,7 +627,7 @@ The available table extras are listed below.
|
|||
"facetable"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=database_color``
|
||||
|
||||
|
|
@ -556,6 +640,8 @@ The available table extras are listed below.
|
|||
|
||||
``GET /fixtures/facetable.json?_extra=renderers``
|
||||
|
||||
Each key is the name of an output format, each value the URL for this data in that format. Plugins can add additional formats using the :ref:`register_output_renderer() plugin hook <plugin_register_output_renderer>`.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -563,7 +649,7 @@ The available table extras are listed below.
|
|||
}
|
||||
|
||||
``custom_table_templates``
|
||||
Custom template names considered for this table
|
||||
Custom template names considered for this table (The first template in this list that exists will be used to render the table on the HTML version of this page. See :ref:`customization_custom_templates`.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=custom_table_templates``
|
||||
|
||||
|
|
@ -576,7 +662,7 @@ The available table extras are listed below.
|
|||
]
|
||||
|
||||
``sorted_facet_results``
|
||||
Facet results sorted for display
|
||||
Facet results sorted for display (The same data as ``facet_results``, as a list in the order used by the HTML interface: facets from :ref:`facet configuration <facets_metadata>` first, then other facets ordered by their number of results.)
|
||||
|
||||
``GET /fixtures/facetable.json?_facet=state&_extra=sorted_facet_results``
|
||||
|
||||
|
|
@ -643,7 +729,7 @@ The available table extras are listed below.
|
|||
true
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=private``
|
||||
|
||||
|
|
@ -652,10 +738,12 @@ The available table extras are listed below.
|
|||
false
|
||||
|
||||
``expandable_columns``
|
||||
Foreign key columns that can be expanded with labels
|
||||
Foreign key columns that can be expanded with labels (See :ref:`expand_foreign_keys` for how to expand these labels.)
|
||||
|
||||
``GET /fixtures/facetable.json?_extra=expandable_columns``
|
||||
|
||||
Each item is a ``[foreign_key, label_column]`` pair: the foreign key relationship, then the column in the other table that would be used as the label for each expanded value.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
|
|
@ -720,7 +808,7 @@ The following extras are available for row JSON responses.
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item for the requested row. The object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -741,7 +829,7 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=debug``
|
||||
|
||||
|
|
@ -803,17 +891,28 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``column_types``
|
||||
Column type assignments for this table
|
||||
Column type assignments for this table (An empty object if no column types have been assigned. Column types can be assigned in :ref:`configuration <table_configuration_column_types>` or using the :ref:`set column type API <TableSetColumnTypeView>`.)
|
||||
|
||||
``GET /fixtures/facetable/1.json?_extra=column_types``
|
||||
|
||||
This example is from an instance where the ``tags`` column has been assigned the ``json`` column type.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{}
|
||||
{
|
||||
"tags": {
|
||||
"type": "json",
|
||||
"config": null
|
||||
}
|
||||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=metadata``
|
||||
|
||||
This table has no metadata, so only an empty ``columns`` object is returned.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -821,7 +920,26 @@ The following extras are available for row JSON responses.
|
|||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -842,7 +960,7 @@ The following extras are available for row JSON responses.
|
|||
"simple_primary_key"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=database_color``
|
||||
|
||||
|
|
@ -851,7 +969,7 @@ The following extras are available for row JSON responses.
|
|||
"9403e5"
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=private``
|
||||
|
||||
|
|
@ -860,10 +978,12 @@ The following extras are available for row JSON responses.
|
|||
false
|
||||
|
||||
``foreign_key_tables``
|
||||
Tables that link to this row using foreign keys
|
||||
Tables that link to this row using foreign keys (May execute additional queries.)
|
||||
|
||||
``GET /fixtures/simple_primary_key/1.json?_extra=foreign_key_tables``
|
||||
|
||||
``count`` is the number of rows in the other table that reference this row, and ``link`` is a URL to browse those rows.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
|
|
@ -921,7 +1041,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
]
|
||||
|
||||
``render_cell``
|
||||
Rendered HTML for each cell using the render_cell plugin hook
|
||||
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
|
||||
|
||||
The ``render_cell`` array has one item per query result row, in the same order as the ``rows`` array. Each object is keyed by column name. Only columns whose rendered value differs from the default are included.
|
||||
|
||||
|
|
@ -941,7 +1061,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``debug``
|
||||
Extra debug information
|
||||
Extra debug information (The contents of this block are not a stable part of the Datasette API and may change without warning.)
|
||||
|
||||
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=debug``
|
||||
|
||||
|
|
@ -1000,10 +1120,12 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``metadata``
|
||||
Metadata about the table, database or stored query
|
||||
Metadata about the table, database or stored query (See :ref:`metadata` for how to attach metadata to tables.)
|
||||
|
||||
``GET /fixtures/neighborhood_search.json?text=town&_extra=metadata``
|
||||
|
||||
For stored queries this returns the full configuration of the query, including the :ref:`stored query options <queries_options>`. For ``?sql=`` queries it returns an empty object.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
|
|
@ -1029,7 +1151,26 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
}
|
||||
|
||||
``extras``
|
||||
Available ?_extra= blocks
|
||||
List of ?_extra= blocks that can be used on this page
|
||||
|
||||
Shape abbreviated from /fixtures/facetable.json?_extra=extras - the full response lists every extra described on this page. ``toggle_url`` is the current URL with that extra added or removed, and ``selected`` is ``true`` for extras included in the current request.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "count",
|
||||
"description": "Total count of rows matching these filters",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json?_extra=extras&_extra=count",
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"name": "extras",
|
||||
"description": "List of ?_extra= blocks that can be used on this page",
|
||||
"toggle_url": "http://localhost/fixtures/facetable.json",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
|
||||
``database``
|
||||
Database name
|
||||
|
|
@ -1041,7 +1182,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
"fixtures"
|
||||
|
||||
``database_color``
|
||||
Color assigned to the database
|
||||
Color assigned to the database (A six character hex color, without the leading ``#``, derived from a hash of the database name and used in the Datasette interface.)
|
||||
|
||||
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=database_color``
|
||||
|
||||
|
|
@ -1050,7 +1191,7 @@ The following extras are available for arbitrary SQL query responses and stored,
|
|||
"9403e5"
|
||||
|
||||
``private``
|
||||
Whether this resource is private to the current actor
|
||||
Whether this resource is private to the current actor (``true`` if the current actor can see this resource but an anonymous user could not. See :ref:`authentication_permissions`.)
|
||||
|
||||
``GET /fixtures/-/query.json?sql=select+1+as+one&_extra=private``
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue