id,page,ref,title,content,breadcrumbs,references
json_api:expand-foreign-keys,json_api,expand-foreign-keys,Expanding foreign key references,"Datasette can detect foreign key relationships and resolve those references into
                labels. The HTML interface does this by default for every detected foreign key
                column - you can turn that off using  ?_labels=off . 
             You can request foreign keys be expanded in JSON using the  _labels=on  or
                 _label=COLUMN  special query string parameters. Here's what an expanded row
                looks like: 
             [
    {
        ""rowid"": 1,
        ""TreeID"": 141565,
        ""qLegalStatus"": {
            ""value"": 1,
            ""label"": ""Permitted Site""
        },
        ""qSpecies"": {
            ""value"": 1,
            ""label"": ""Myoporum laetum :: Myoporum""
        },
        ""qAddress"": ""501X Baker St"",
        ""SiteOrder"": 1
    }
] 
             The column in the foreign key table that is used for the label can be specified
                in  metadata.json  - see  Specifying the label column for a table .","[""JSON API""]",[]
json_api:id2,json_api,id2,Table arguments,The Datasette table view takes a number of special query string arguments.,"[""JSON API""]",[]
json_api:json-api-cors,json_api,json-api-cors,Enabling CORS,"If you start Datasette with the  --cors  option, each JSON endpoint will be
                served with the following additional HTTP headers: 
             [[[cog
from datasette.utils import add_cors_headers
import textwrap
headers = {}
add_cors_headers(headers)
output = ""\n"".join(""{}: {}"".format(k, v) for k, v in headers.items())
cog.out(""\n::\n\n"")
cog.out(textwrap.indent(output, '    '))
cog.out(""\n\n"") 
             ]]] 
             Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Expose-Headers: Link
Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS
Access-Control-Max-Age: 3600 
             [[[end]]] 
             This allows JavaScript running on any domain to make cross-origin
                requests to interact with the Datasette API. 
             If you start Datasette without the  --cors  option only JavaScript running on
                the same domain as Datasette will be able to access the API. 
             Here's how to serve  data.db  with CORS enabled: 
             datasette data.db --cors","[""JSON API""]",[]
json_api:json-api-default,json_api,json-api-default,Default representation,"The default JSON representation of data from a SQLite table or custom query
                looks like this: 
             {
  ""ok"": true,
  ""rows"": [
    {
      ""id"": 3,
      ""name"": ""Detroit""
    },
    {
      ""id"": 2,
      ""name"": ""Los Angeles""
    },
    {
      ""id"": 4,
      ""name"": ""Memnonia""
    },
    {
      ""id"": 1,
      ""name"": ""San Francisco""
    }
  ],
  ""truncated"": false
} 
             ""ok""  is always  true  if an error did not occur. 
             The  ""rows""  key is a list of objects, each one representing a row. 
             The  ""truncated""  key lets you know if the query was truncated. This can happen if a SQL query returns more than 1,000 results (or the  max_returned_rows  setting). 
             For table pages, an additional key  ""next""  may be present. This indicates that the next page in the pagination set can be retrieved using  ?_next=VALUE .","[""JSON API""]",[]
json_api:json-api-discover-alternate,json_api,json-api-discover-alternate,Discovering the JSON for a page,"Most of the HTML pages served by Datasette provide a mechanism for discovering their JSON equivalents using the HTML  link  mechanism. 
             You can find this near the top of the source code of those pages, looking like this: 
             <link rel=""alternate""
  type=""application/json+datasette""
  href=""https://latest.datasette.io/fixtures/sortable.json""> 
             The JSON URL is also made available in a  Link  HTTP header for the page: 
             Link: https://latest.datasette.io/fixtures/sortable.json; rel=""alternate""; type=""application/json+datasette""","[""JSON API""]",[]
json_api:json-api-pagination,json_api,json-api-pagination,Pagination,"The default JSON representation includes a  ""next_url""  key which can be used to access the next page of results. If that key is null or missing then it means you have reached the final page of results. 
             Other representations include pagination information in the  link  HTTP header. That header will look something like this: 
             link: <https://latest.datasette.io/fixtures/sortable.json?_next=d%2Cv>; rel=""next"" 
             Here is an example Python function built using  requests  that returns a list of all of the paginated items from one of these API endpoints: 
             def paginate(url):
    items = []
    while url:
        response = requests.get(url)
        try:
            url = response.links.get(""next"").get(""url"")
        except AttributeError:
            url = None
        items.extend(response.json())
    return items","[""JSON API""]","[{""href"": ""https://requests.readthedocs.io/"", ""label"": ""requests""}]"
json_api:json-api-shapes,json_api,json-api-shapes,Different shapes,"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
                options: 
             
                 
                     ?_shape=objects  -  ""rows""  is a list of JSON key/value objects - the default 
                 
                 
                     ?_shape=arrays  -  ""rows""  is a list of lists, where the order of values in each list matches the order of the columns 
                 
                 
                     ?_shape=array  - a JSON array of objects - effectively just the  ""rows""  key from the default representation 
                 
                 
                     ?_shape=array&_nl=on  - a newline-separated list of JSON objects 
                 
                 
                     ?_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=arrays  looks like this: 
             {
  ""ok"": true,
  ""next"": null,
  ""rows"": [
    [3, ""Detroit""],
    [2, ""Los Angeles""],
    [4, ""Memnonia""],
    [1, ""San Francisco""]
  ]
} 
             _shape=array  looks like this: 
             [
  {
    ""id"": 3,
    ""name"": ""Detroit""
  },
  {
    ""id"": 2,
    ""name"": ""Los Angeles""
  },
  {
    ""id"": 4,
    ""name"": ""Memnonia""
  },
  {
    ""id"": 1,
    ""name"": ""San Francisco""
  }
] 
             _shape=array&_nl=on  looks like this: 
             {""id"": 1, ""value"": ""Myoporum laetum :: Myoporum""}
{""id"": 2, ""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""}
{""id"": 3, ""value"": ""Pinus radiata :: Monterey Pine""} 
             _shape=arrayfirst  looks like this: 
             [1, 2, 3] 
             _shape=object  looks like this: 
             {
  ""1"": {
    ""id"": 1,
    ""value"": ""Myoporum laetum :: Myoporum""
  },
  ""2"": {
    ""id"": 2,
    ""value"": ""Metrosideros excelsa :: New Zealand Xmas Tree""
  },
  ""3"": {
    ""id"": 3,
    ""value"": ""Pinus radiata :: Monterey Pine""
  }
] 
             The  object  shape is only available for queries against tables - custom SQL
                queries and views do not have an obvious primary key so cannot be returned using
                this format. 
             The  object  keys are always strings. If your table has a compound primary
                key, the  object  keys will be a comma-separated string.","[""JSON API""]",[]
json_api:json-api-special,json_api,json-api-special,Special JSON arguments,"Every Datasette endpoint that can return JSON also accepts the following
                query string arguments: 
             
                 
                     ?_shape=SHAPE 
                     
                         The shape of the JSON to return, documented above. 
                     
                 
                 
                     ?_nl=on 
                     
                         When used with  ?_shape=array  produces newline-delimited JSON objects. 
                     
                 
                 
                     ?_json=COLUMN1&_json=COLUMN2 
                     
                         If any of your SQLite columns contain JSON values, you can use one or more
                             _json=  parameters to request that those columns be returned as regular
                            JSON. Without this argument those columns will be returned as JSON objects
                            that have been double-encoded into a JSON string value. 
                         Compare  this query without the argument  to  this query using the argument 
                     
                 
                 
                     ?_json_infinity=on 
                     
                         If your data contains infinity or -infinity values, Datasette will replace
                            them with None when returning them as JSON. If you pass  _json_infinity=1 
                            Datasette will instead return them as  Infinity  or  -Infinity  which is
                            invalid JSON but can be processed by some custom JSON parsers. 
                     
                 
                 
                     ?_timelimit=MS 
                     
                         Sets a custom time limit for the query in ms. You can use this for optimistic
                            queries where you would like Datasette to give up if the query takes too
                            long, for example if you want to implement autocomplete search but only if
                            it can be executed in less than 10ms. 
                     
                 
                 
                     ?_ttl=SECONDS 
                     
                         For how many seconds should this response be cached by HTTP proxies? Use
                             ?_ttl=0  to disable HTTP caching entirely for this request. 
                     
                 
                 
                     ?_trace=1 
                     
                         Turns on tracing for this page: SQL queries executed during the request will
                            be gathered and included in the response, either in a new  ""_traces""  key
                            for JSON responses or at the bottom of the page if the response is in HTML. 
                         The structure of the data returned here should be considered highly unstable
                            and very likely to change. 
                         Only available if the  trace_debug  setting is enabled.","[""JSON API""]","[{""href"": ""https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array"", ""label"": ""this query without the argument""}, {""href"": ""https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array&_json=d"", ""label"": ""this query using the argument""}]"
json_api:json-api-write,json_api,json-api-write,The JSON write API,"Datasette provides a write API for JSON data. This is a POST-only API that requires an authenticated API token, see  API Tokens . The token will need to have the specified  Permissions .","[""JSON API""]",[]