Docs about methods for updating records

docs/api/reading.md

@@ -2,6 +2,9 @@
 
 ### Tables and Views
 
+* ✅ Cacheable, prefetchable
+* ✅ Idempotent
+
 The list of accessible tables and views is provided at
 
 ```HTTP
@@ -32,6 +35,9 @@ on database permissions.
 
 ### Stored Procedures
 
+* ❌ Cannot necessarily be cached or prefetched
+* ❌ Not necessarily idempotent
+
 Every stored procedure is accessible under the `/rpc` prefix. The
 API endpoint supports only POST which executes the function.
 

docs/api/writing.md

@@ -2,12 +2,130 @@
 
 ### Record Creation
 
+* ❌ Cannot be cached or prefetched
+* ❌ Not idempotent
+
+To create a row in a database table post a JSON object whose keys
+are the names of the columns you would like to create. Missing keys
+will be set to default values when applicable.
+
+```HTTP
+POST /table_name
+{ "col1": "value1", "col2": "value2" }
+```
+
+The response will include a `Location` header describing where to
+find the new object. If you would like to get the full object back
+in the response to your request, include the header `Prefer:
+return=representation`. That way you won't have to make another
+HTTP call to discover properties that may have been filled in on
+the server side.
+
 ### Bulk Insertion
 
+* ❌ Cannot be cached or prefetched
+* ❌ Not idempotent
+
+While regular insertion uses JSON to encode the value, bulk insertion
+uses CSV. Simply post to a table route with `Content-Type: text/csv`
+and include the names of the columns as the first row. For instance
+
+```HTTP
+POST /people
+name,age,height
+J Doe,62,70
+Jonas,10,55
+```
+
+An empty field (`,,`) is coerced to an empty string and the reserved
+word `NULL` is mapped to the SQL null value. Note that there should
+be no spaces between the column names and commas.
+
+The server sends a multipart response for bulk insertions. Each part
+contains a Location header with URL of each created resource.
+
+```HTTP
+Content-Type: application/json
+Location: /festival?name=eq.Venice%20Film%20Festival
+
+
+--postgrest_boundary
+Content-Type: application/json
+Location: /festival?name=eq.Cannes%20Film%20Festival
+```
+
 ### Upsertion
 
+* ❌ Cannot be cached or prefetched
+* ✅ Idempotent
+
+To insert or update a single row use the `PUT` verb on a properly
+filtered table url:
+
+```HTTP
+PUT /table_name?primary_key=eq.foo
+{ "col1": "value1", "col2": "value2" }
+```
+
+The request must satisfy two things. First all columns must be
+specified (because a default value might be a changing value which
+would violate idempotence). Second the URL must match the URL you
+would use to get the value of the resource. This means that all
+primary key columns must be included in the filter (there are more
+than one when the primary key is compound).
+
+If you would like to get the full object back in the response to
+your request, include the header `Prefer: return=representation`.
+It will of match exactly the object you sent though.
+
 ### Bulk Updates
 
+* ❌ Cannot be cached or prefetched
+* ❌ Not idempotent
+
+To change parts of a resource or resources use the `PATCH` verb.
+For instance, here is how to mark all young people as children.
+
+```HTTP
+PATCH /people?age=lt.13
+{
+  "person_type": "child"
+}
+```
+
+This affects any rows matched by the url param filters, overwrites
+any fields specified in in the payload JSON and leaves the other
+fields unaffected. Note that although the payload is not in the
+JSON patch format specified by
+[RFC6902](https://tools.ietf.org/html/rfc6902), HTTP does not specify
+which patch format to use. Our format is more pleasant, meant for
+basic field replacements, and not at all "incorrect."
+
 ### Deletion
 
+* ❌ Cannot be cached or prefetched
+* ✅ Idempotent
+
+Simply use the `DELETE` verb. All recors that match your filter
+will be removed. For instance deleting inactive users:
+
+```HTTP
+DELETE /user?active=eq.false
+```
+
 ### Protecting Dangerous Actions
+
+Notice that it is very easy to delete or update many records at
+once. In fact forgetting a filter will affect an entire table!
+
+
+<div class="admonition warning">
+    <p class="admonition-title">Invitation to Contribute</p>
+
+    <p>We would like to investigate nginx rules to guard dangerous
+    actions, perhaps requiring a confirmation header or query param
+    to perform the action.</p>
+
+    <p>You're invited to research this option and contribute to
+    this documentation.</p>
+</div>