diff --git a/docs/authentication.rst b/docs/authentication.rst index 72ac5fa6..7d4d019d 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -1151,6 +1151,8 @@ It also provides an interface for running hypothetical permission checks against This is designed to help administrators and plugin authors understand exactly how permission checks are being carried out, in order to effectively configure Datasette's permission system. +These debug endpoints are exempt from the :ref:`JSON API stability promise ` - their JSON shapes may change in future releases. + .. _AllowedResourcesView: Allowed resources view diff --git a/docs/introspection.rst b/docs/introspection.rst index 2d13f68b..ea94b70d 100644 --- a/docs/introspection.rst +++ b/docs/introspection.rst @@ -9,6 +9,8 @@ Each of these pages can be viewed in your browser. Add ``.json`` to the URL to g JSON responses that return an object include an ``"ok": true`` key, consistent with the rest of the :ref:`JSON API `. +The introspection endpoints documented on this page are covered by the :ref:`JSON API stability promise `, with the exception of the debug endpoints ``/-/threads``, ``/-/actions`` and ``/-/jump``, whose shapes may change in future releases. + .. _JsonDataView_metadata: /-/metadata diff --git a/docs/json_api.rst b/docs/json_api.rst index dc611a39..4b1f26d2 100644 --- a/docs/json_api.rst +++ b/docs/json_api.rst @@ -9,6 +9,53 @@ through the Datasette user interface can also be accessed as JSON via the API. To access the API for a page, either click on the ``.json`` link on that page or edit the URL and add a ``.json`` extension to it. +.. _json_api_stability: + +API stability +------------- + +Datasette 1.0 makes a stability promise for its JSON API: the endpoints, +parameters and response keys documented here and on the pages this +documentation links to will not change in backwards-incompatible ways for +the duration of the 1.x release series. + +Stability means: + +- Documented endpoints will keep their URLs, methods, parameters and + permission requirements. +- Documented response keys will keep their names and types. New keys may be + **added** in any release - clients should ignore keys they do not + recognize. +- The documented ``?_extra=`` names, ``?_shape=`` values and + :ref:`column filter operators ` are stable. +- Pagination tokens - the ``"next"`` key and ``?_next=`` parameter - are + **opaque strings**. Pass them back exactly as you received them; their + internal structure is not part of the API and can change at any time. +- The :ref:`standard error format ` and the + :ref:`API token format and restriction semantics ` are + stable, including the action abbreviations stored inside signed tokens. + +Some JSON endpoints are **exempt** from this promise: + +- Endpoints that are not documented include this marker key in their + responses and can change at any time:: + + "unstable": "This API is not part of Datasette's stable interface and may change at any time" + + This currently covers the instance homepage (``/.json``), the stored + query ``analyze``/``store``/``definition`` endpoints, ``/-/query/parameters``, + ``/-/execute-write/analyze`` and the JSON returned by the ``/-/permissions`` + debug playground. +- Debug and support endpoints are documented so you can use them, but their + JSON shapes are not frozen: :ref:`/-/threads `, + :ref:`/-/actions `, :ref:`/-/jump `, + the :ref:`permission debug endpoints ` + (``/-/allowed``, ``/-/rules``, ``/-/check``) and the + :ref:`table autocomplete endpoint `. +- Response keys explicitly labeled as unstable in this documentation, such + as the ``"analysis"`` block returned by :ref:`execute-write ` + and the ``debug`` and ``request`` extras. + .. _json_api_default: Default representation @@ -1612,7 +1659,7 @@ Unsupported SQL operations are rejected by default. ``VACUUM`` is not allowed in A successful response includes a message, the SQLite ``rowcount``, a ``"rows"`` list, a ``"truncated"`` flag and a summary of the operations that were executed: -The shape of the ``"analysis"`` block is not yet considered a stable API and may change in future Datasette releases. +The shape of the ``"analysis"`` block is not part of the :ref:`stable API ` and may change in future Datasette releases. .. code-block:: json diff --git a/stable-api-recommendations.md b/stable-api-recommendations.md index baac80f7..b86d8228 100644 --- a/stable-api-recommendations.md +++ b/stable-api-recommendations.md @@ -378,13 +378,17 @@ Concerns: --- -## 9. Define stability tiers explicitly (P1 — documentation, not code) — partially implemented +## 9. Define stability tiers explicitly (P1 — documentation, not code) — ✅ IMPLEMENTED -> **Status:** undocumented JSON endpoints now self-describe with an -> `"unstable": "This API is not part of Datasette's stable interface and -> may change at any time"` key (homepage, queries analyze/store/definition, -> query parameters, execute-write analyze, permissions playground POST). -> The written tier documentation remains to be done. +> **Status:** implemented. Undocumented JSON endpoints self-describe with +> an `"unstable"` marker key, and `docs/json_api.rst` now opens with an +> "API stability" section (`json_api_stability`) declaring the 1.x +> promise: documented endpoints/keys are stable with additive-only +> changes, pagination tokens are opaque, the error format and token +> restriction semantics are stable, and the exempt tiers (marker-key +> endpoints, debug/support endpoints, explicitly-unstable keys) are +> listed. Cross-referenced from the introspection and permission-debug +> docs. Not everything under `/-/` can or should carry a 1.0 guarantee. Recommend shipping 1.0 with an explicit three-tier contract, per endpoint: @@ -431,8 +435,8 @@ Two details make tiering urgent rather than optional: `permissions-debug` (§6).~~ ✅ Done. 6. ~~401 (not silent-anonymous) for invalid/expired bearer tokens (§1c).~~ ✅ Done. -7. Publish explicit stability tiers, including extras and pagination-token - opacity (§9). +7. ~~Publish explicit stability tiers, including extras and pagination-token + opacity (§9).~~ ✅ Done. 8. Resolve the looks-like-a-bug list (§8), especially ~~trusted-query delete and row-delete 500~~ (both done).