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.

Yeah, every time I see something cool done with triggers, I remember that I need to start using triggers.

That trigger solution is pretty neat!

This could use a new plugin hook, too. I don't want to complicate your life too much, but for things like GIS, I'd want a way to turn regular JSON into SpatiaLite geometries or combine X/Y coordinates into point geometries and such. Happy to help however I can.

@eyeseast Maybe you could do this with triggers? Like you can insert JSON-friendly data into a "raw" table, and create a trigger that transforms that inserted data into the proper table

Here's an example:

```sql -- meant to be updated from a Datasette insert create table points_raw(longitude int, latitude int);

-- the target table with proper spatliate geometries create table points(point geometry);

CREATE TRIGGER insert_points_raw INSERT ON points_raw BEGIN insert into points(point) values (makepoint(new.longitude, new.latitude)) END; ```

You could then POST a new row to points_raw like this: POST /db/points_raw Authorization: Bearer xxx Content-Type: application/json { "row": { "longitude": 27.64356, "latitude": -47.29384 } }

Then SQLite with run the trigger and insert a new row in points with the correct geometry point. Downside is you'd have duplicated data with points_raw, but maybe it could be a TEMP table (or have a cron that deletes all rows from that table every so often?)

That's reasonable. Canned queries and custom endpoints are certainly going to give more room for specific needs.

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 could use a new plugin hook, too. I don't want to complicate your life too much, but for things like GIS, I'd want a way to turn regular JSON into SpatiaLite geometries or combine X/Y coordinates into point geometries and such. Happy to help however I can.

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.

How are you tying the bearer token to identity? I'm excited to see this feature, and since Sandstorm controls API access using the same header, it also will transparently support the API documentation here, but we strip the bearer before the request reaches the app (replacing it with our existing auth headers, of course).

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)