So new API design is:

POST /db/table/-/insert Authorization: Bearer xxx Content-Type: application/json { "row": { "id": 1, "name": "New record" } } Returns: 201 Created { "row": [{ "id": 1, "name": "New record" }] }

I'm going to use this endpoint for bulk inserts too, so I'm closing this issue and continuing the work here: - #1866

API design: (**UPDATE: this was later changed to POST /db/table/-/insert)

POST /db/table Authorization: Bearer xxx Content-Type: application/json { "row": { "id": 1, "name": "New record" } } Returns: 201 Created { "row": { "id": 1, "name": "New record" } } You can omit optional fields in the input, including the ID field. The returned object will always include all fields - and will even include rowid if your object doesn't have a primary key of its own.

I decided to use "row" as the key in both request and response, to preserve space for other future keys - one that tells you that the table has been created, for example.

And the response to "inserted": [{...}] - it will be the same for bulk inserts.

I'm going to change the incoming JSON back to {"row": {...}} - no need to POST {"insert": ...} to something with /-/insert in the URL already.

Need to implement the new URL design from: - #1868

This is now going to be /db/table/-/insert - and it will eventually handle bulk inserts as well as single inserts.

Updated docs: https://docs.datasette.io/en/1.0-dev/json_api.html#inserting-a-single-row

I'm going to change the design of this to: { "insert": { "title" :"..." } } Renaming "row" to "insert".

This will be consistent with adding "drop": true for dropping a table, and maybe other verbs like for modifying the schema.

The API response will look like this:

json { "inserted_row": { "id": 1, "title": "..." } }

I should probably refactor this to use sqlite-utils, since I'm going to want to use that later for the feature that automatically creates tables.

Might make it easier to solve the rowid issues too.

Also need a test for invalid JSON (currently triggers a 500 HTML error).

And come up with a whole bunch of tests for weird table shapes, surprising column names, different types etc.

Also need to think about transactions - it should use them!

Documentation for this first draft of the API: https://docs.datasette.io/en/1.0-dev/json_api.html#inserting-a-single-row

It currently returns errors as HTML - it needs to return errors as JSON. Also the errors need comprehensive test coverage.

I'm also worried about what happens if you use it on a table that doesn't use an integer primary key - need to check that. I think this code may break:

https://github.com/simonw/datasette/blob/51c436fed29205721dcf17fa31d7e7090d34ebb8/datasette/views/table.py#L155-L171

Plus will rowid tables without an explicit primary key return the rowid column? They should.

That trigger solution is pretty neat!

The datasette insert concept included plugin support, with the idea of being able to support things like SpatiaLite files: - #1160

I think this API mechanism is going to be a bit less exciting than that - it will be low-level for inserting rows, and if you want to do something fancier you can use a canned query that feeds incoming GeoJSON to a SpatiaLite function instead.

This is going to tie into Datasette's existing permissions mechanism, so plugins will be able to define their own custom mechanisms for tokens to be attached to a specific identity: https://docs.datasette.io/en/stable/authentication.html

There's only one plugin for API tokens at the moment, which is this one: https://datasette.io/plugins/datasette-auth-tokens

I'm actually planning on adding another, default token mechanism to Datasette itself as part of this work:

• 1852

It may well be that datasette-sandstorm-support needs to add something custom here too.

Interesting open question: how should validation errors (if any) be returned?

The two forms of validation I can think of at first are:

• Missing keys which are marked as not null in the schema
• Keys that do not match to existing columns (if you didn't pass "alter": true, an option I am considering)