Datasette 1.0 alpha 1

This alpha release is a preview of Datasette 1.0.

Datasette 1.0 marks a significant milestone in the project: it is the point from which various aspects of Datasette can be considered "stable", in that code developed against them should expect not to be broken by future releases in the 1.x series.

This will hold true until the next major version release, Datasette 2.0 - which we hope to hold off releasing for as long as possible.

The following Datasette components should be be considered stable after 1.0:

• The plugin API. Plugins developed against 1.0 should continue to work unmodified throughout the 1.x series.
• The JSON API. Code written that interacts with Datasette's default JSON web API should continue to work.
• The template context. If you build custom templates against Datasette your custom pages should continue to work.

Note that none of these components will cease to introduce new features. New plugin hooks, new JSON APIs and new template context variables can be introduced without breaking existing code.

Since this alpha release previews features that will be frozen for 1.0, please test this thoroughly against your existing Datasette projects.

You can install the alpha using:

pip install datasette==1.0a0

JSON API changes

The most significant changes introduced in this new alpha concern Datasette's JSON API.

The default JSON returned by the /database/table.json endpoint has changed. It now returns an object with two keys: rows - which contains a list of objects representing the rows in the table or query, and more containing a boolean that shows if there are more rows or if this object contains them all.

json { "rows": [{ "id": 1, "name": "Name 1" }, { "id": 2, "name": "Name 2" }], "more": false } [ Initially I thought about going with next_url, which would be null if you have reached the last page of records. Maybe that would be better? But since next_url cannot be provided on query pages, should this be part of the default format at all? ]

Use ?_extra= to retrieve extra fields

The default format can be expanded using one or more ?_extra= parameters. This takes names of extra keys you would like to include. These can be comma-separated or ?_extra= can be applied multiple times.

For example:

/database/table.json?_extra=total

This adds a "total": 124 field to the returned JSON.

[ Question: if you do ?_facet=foo then do you still need to do ?_extra=facets - I think not? ]

Redesigned template context

Warning: if you use any custom templates with your Datasette instance they are likely to break when you upgrade to 1.0.

The template context has been redesigned to be based on the documented JSON API. This means that the template context can be considered stable going forward, so any custom templates you implement should continue to work when you upgrade Datasette in the future.