First draft of insert row write API, refs #1851

docs/authentication.rst

@@ -547,6 +547,18 @@ Actor is allowed to view (and execute) a :ref:`canned query <canned_queries>` pa
 
 Default *allow*.
 
+.. _permissions_insert_row:
+
+insert-row
+----------
+
+Actor is allowed to insert rows into a table.
+
+``resource`` - tuple: (string, string)
+    The name of the database, then the name of the table
+
+Default *deny*.
+
 .. _permissions_execute_sql:
 
 execute-sql

docs/cli-reference.rst

@@ -229,6 +229,8 @@ These can be passed to ``datasette serve`` using ``datasette serve --setting nam
                                    database files (default=True)
       allow_signed_tokens          Allow users to create and use signed API tokens
                                    (default=True)
+      max_signed_tokens_ttl        Maximum allowed expiry time for signed API tokens
+                                   (default=0)
       suggest_facets               Calculate and display suggested facets
                                    (default=True)
       default_cache_ttl            Default HTTP cache TTL (used in Cache-Control:

docs/json_api.rst

@@ -455,3 +455,41 @@ You can find this near the top of the source code of those pages, looking like t
 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_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 :ref:`CreateTokenView`.
+
+.. _json_api_write_insert_row:
+
+Inserting a single row
+~~~~~~~~~~~~~~~~~~~~~~
+
+This requires the :ref:`permissions_insert_row` permission.
+
+::
+
+    POST /<database>/<table>
+    Content-Type: application/json
+    Authorization: Bearer dstok_<rest-of-token>
+    {
+        "row": {
+            "column1": "value1",
+            "column2": "value2"
+        }
+    }
+
+If successful, this will return a ``201`` status code and the newly inserted row, for example:
+
+.. code-block:: json
+
+    {
+        "row": {
+            "id": 1,
+            "column1": "value1",
+            "column2": "value2"
+        }
+    }