github/datasette
1
0
Fork 0
mirror of https://github.com/simonw/datasette.git synced 2025-12-10 16:51:24 +01:00
Code Issues Projects Releases Packages Wiki Activity

Updated JSON API shape documentation, refs #262

Browse source
This commit is contained in:
Simon Willison 2023-03-28 23:21:42 -07:00
commit 4c1e277edb
1 changed files with 75 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

147
docs/json_api.rst
View file

@ -15,38 +15,37 @@ Different shapes
---------------- ----------------
The default JSON representation of data from a SQLite table or custom query The default JSON representation of data from a SQLite table or custom query
looks like this:: looks like this:
.. code-block:: json
{ {
"database": "sf-trees", "ok": true,
"table": "qSpecies", "next": null,
"columns": [ "rows": [
"id", {
"value" "id": 3,
], "name": "Detroit"
"rows": [ },
{ {
"id": 1, "id": 2,
"value": "Myoporum laetum :: Myoporum" "name": "Los Angeles"
}, },
{ {
"id": 2, "id": 4,
"value": "Metrosideros excelsa :: New Zealand Xmas Tree" "name": "Memnonia"
}, },
{ {
"id": 3, "id": 1,
"value": "Pinus radiata :: Monterey Pine" "name": "San Francisco"
} }
], ]
"count": 195002,
"truncated": false,
"next": "100",
"next_url": "http://127.0.0.1:8001/sf-trees-02c8ef1/qSpecies.json?_next=100",
"query_ms": 1.9571781158447266
} }
The ``columns`` key lists the columns that are being returned, and the ``rows`` The ``rows`` key is a list of objects, each one representing a row. ``next`` indicates if
key then returns a list of objects, each one representing a row. there is another page, and ``ok`` is always ``true`` if an error did not occur.
If ``next`` is present then the next page in the pagination set can be retrieved using ``?_next=VALUE``.
The ``_shape`` parameter can be used to access alternative formats for the The ``_shape`` parameter can be used to access alternative formats for the
``rows`` key which may be more convenient for your application. There are three ``rows`` key which may be more convenient for your application. There are three
@ -59,42 +58,42 @@ options:
* ``?_shape=arrayfirst`` - a flat JSON array containing just the first value from each row * ``?_shape=arrayfirst`` - a flat JSON array containing just the first value from each row
* ``?_shape=object`` - a JSON object keyed using the primary keys of the rows * ``?_shape=object`` - a JSON object keyed using the primary keys of the rows
``_shape=arrays`` looks like this:: ``_shape=arrays`` looks like this:
.. code-block:: json
{ {
"database": "sf-trees", "ok": true,
... "next": null,
"rows": [ "rows": [
[ [3, "Detroit"],
1, [2, "Los Angeles"],
"Myoporum laetum :: Myoporum" [4, "Memnonia"],
], [1, "San Francisco"]
[ ]
2,
"Metrosideros excelsa :: New Zealand Xmas Tree"
],
[
3,
"Pinus radiata :: Monterey Pine"
]
]
} }
``_shape=array`` looks like this:: ``_shape=array`` looks like this:
.. code-block:: json
[ [
{ {
"id": 1, "id": 3,
"value": "Myoporum laetum :: Myoporum" "name": "Detroit"
}, },
{ {
"id": 2, "id": 2,
"value": "Metrosideros excelsa :: New Zealand Xmas Tree" "name": "Los Angeles"
}, },
{ {
"id": 3, "id": 4,
"value": "Pinus radiata :: Monterey Pine" "name": "Memnonia"
} },
{
"id": 1,
"name": "San Francisco"
}
] ]
``_shape=array&_nl=on`` looks like this:: ``_shape=array&_nl=on`` looks like this::
@ -103,25 +102,29 @@ options:
{"id": 2, "value": "Metrosideros excelsa :: New Zealand Xmas Tree"} {"id": 2, "value": "Metrosideros excelsa :: New Zealand Xmas Tree"}
{"id": 3, "value": "Pinus radiata :: Monterey Pine"} {"id": 3, "value": "Pinus radiata :: Monterey Pine"}
``_shape=arrayfirst`` looks like this:: ``_shape=arrayfirst`` looks like this:
.. code-block:: json
[1, 2, 3] [1, 2, 3]
``_shape=object`` looks like this:: ``_shape=object`` looks like this:
.. code-block:: json
{ {
"1": { "1": {
"id": 1, "id": 1,
"value": "Myoporum laetum :: Myoporum" "value": "Myoporum laetum :: Myoporum"
}, },
"2": { "2": {
"id": 2, "id": 2,
"value": "Metrosideros excelsa :: New Zealand Xmas Tree" "value": "Metrosideros excelsa :: New Zealand Xmas Tree"
}, },
"3": { "3": {
"id": 3, "id": 3,
"value": "Pinus radiata :: Monterey Pine" "value": "Pinus radiata :: Monterey Pine"
} }
] ]
The ``object`` shape is only available for queries against tables - custom SQL The ``object`` shape is only available for queries against tables - custom SQL