I need this for Datasette Cloud, and in thinking it through I realized that it's really time Datasette grew a default write API as well.

I'm going to mostly model this off sqlite-utils, since I've spent a bunch of time iterating on a pseudo-JSON API for that over the past few years (piping JSON to stdin etc).

I want this for Datasette 1.0. I'm going to be building it in the new 1.0-dev branch, which is automatically deployed to https://latest-1-0-dev.datasette.io/ running on Cloud Run.

API features to build:

• [x] #1852
• [x] #1856
• [x] #1857
• [x] #1858
• [x] #1859
• [x] #1871
• [x] #1888
• [x] #1868
• [x] #1851
• [x] #1863
• [x] #1864
• [x] #1866
• [x] https://github.com/simonw/datasette/issues/1882
• [x] #1862
• [x] #1874
• [x] https://github.com/simonw/datasette/issues/1887
• [x] #1877

Bumped to later on:

• 1855

• 1878

• 1873

• 1875

• Make sure CORS works
• https://github.com/simonw/datasette/issues/1889
• Alter a table - sqlite-utils transform style (more powerful than straight ALTER)
• Execute SQL against a write connection
• Maybe even multiple write SQL statements bundled in a single transaction
• https://github.com/simonw/datasette/issues/1867

I attempted the release just now - https://github.com/simonw/datasette/releases/tag/1.0a0 - and got an unexpected test failure:

https://github.com/simonw/datasette/actions/runs/3577355358/attempts/1

```

  assert delete_response.status_code == 200

E assert 404 == 200 E + where 404 = <Response [404 Not Found]>.status_code

/home/runner/work/datasette/datasette/tests/test_api_write.py:396: AssertionError =========================== short test summary info ============================ FAILED tests/test_api_write.py::test_delete_row[compound_pk_table-row_for_create2-pks2-article,k] - assert 404 == 200 + where 404 = <Response [404 Not Found]>.status_code ``` I hit "retry" on that test but I expect it to fail again.

I'm committed enough to the 1.0 work now that I'm ready for the main branch to reflect that instead.

If I need to make any dot-releases against 0.63 I can do those from a branch.

This release will mainly help preview the new Datasette write API: - #1850

API design: POST /db/table/row-pks/-/delete Or... DELETE /db/table/row-pks/-/delete I'm just going to do POST for the moment, like I did here: - #1874

Permission: delete-row

Still needed:

• [ ] Tests for rowid tables
• [ ] Tests for compound primary keys

Found myself needing this to write the tests for: - #1864

API design:

POST /db/table/row-pks/-/update { "field": "updated_value" } Only the fields that you pass will be updated.

Maybe this is the wrong design though? The design for insert currently looks like this:

• https://github.com/simonw/datasette/issues/1851#issuecomment-1294224185

POST /db/table/-/insert Authorization: Bearer xxx Content-Type: application/json { "row": { "id": 1, "name": "New name" } } I could use the same format for /-/update, but in this case the API doesn't require you to pass every field so "row" doesn't seem like the right key.

I think I'll go with this:

POST /db/table/1/-/update Authorization: Bearer xxx Content-Type: application/json { "update": { "name": "New name" } } The benefit of having an "update" key is that it allows me to use other keys in the future. Maybe a "alter": true key to indicate that new columns should be added if they are missing.

Same problem as this one: - https://github.com/simonw/datasette-lite/issues/56

Caused this failure: https://github.com/simonw/datasette/actions/runs/3500765964

In trying to write this I realize that there's a lot of duplicated code with delete row, specifically around resolving the incoming URL into a row (or a database or a table).

Since this is so common, I think it's worth extracting the logic out first.

Originally posted by @simonw in https://github.com/simonw/datasette/issues/1863#issuecomment-1317755263

In playing with the API explorer just now I realized it's way too easy to accidentally drop a table using it.

Originally posted by @simonw in https://github.com/simonw/datasette/issues/1871#issuecomment-1313097057

Added drop table API in: - #1874

POST /db/table/-/drop

Require drop-table permission.

It's interesting to also think about what the form-based UI for this could look like - since that would involve users creating new columns of different types on the fly.

Will need the create-table permission.

It really feels like this should be accompanied by a /db/-/create API for creating tables. I had to add that to sqlite-utils eventually (initially it only supported creating by passing in an example document):

https://sqlite-utils.datasette.io/en/stable/cli.html#cli-create-table

Originally posted by @simonw in https://github.com/simonw/datasette/issues/1862#issuecomment-1299073433

Similar to https://github.com/simonw/datasette-insert/blob/0.8/README.md#inserting-data-and-creating-tables

I expect this to become by far the most common way that data gets into a Datasette instance - more so than the individual row API in: - #1851

Controlled by a new insert-row permission.

My original design for this issue: - #1851

Was POST /db/table with JSON of {"insert": {...}}.

Refs: - #1871

I noticed the API explorer doesn't show any links on https://latest-1-0-dev.datasette.io/-/api because the fixtures database is immutable.

It should still show read examples there.

The API will be much easier to develop if there's a page that helps you execute JSON POSTs against it.

The CLI equivalent of the /-/create-token page.

It's currently possible to use /-/create-token to create a token that lasts forever.

Some administrators may wish to have a maximum expiry instead. I should support that with a setting.

It strikes me that users should NOT be able to use a token to create additional tokens.

The current design actually does allow that, since the dstok_ Bearer token can be used to authenticate calls to the /-/create-token page.

So I think I need a mechanism whereby that page can only allow access to users authenticated by cookie.

Not obvious how to do that though, since Datasette's authentication actor system is designed to abstract that detail away!

Originally posted by @simonw in https://github.com/simonw/datasette/issues/1850#issuecomment-1291417100

Had some design thoughts here: https://github.com/simonw/datasette/issues/1852#issuecomment-1291272280

I liked this option the most:

--setting allow_create_tokens off

API authentication will be via Authorization: Bearer XXX request headers.

I'm inclined to add a default token mechanism to Datasette based on tokens that are signed with the DATASETTE_SECRET. Maybe the root user can access /-/create-token which provides a UI for generating a time-limited signed token? Could also have a datasette token command for creating such tokens at the command-line.

Plugins can then define alternative ways of creating tokens, such as the existing https://datasette.io/plugins/datasette-auth-tokens plugin.

Originally posted by @simonw in https://github.com/simonw/datasette/issues/1850#issuecomment-1289706439