124 lines
3.3 KiB
Markdown
124 lines
3.3 KiB
Markdown
## Updating Data
|
|
|
|
### 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
|
|
|
|
You can POST a JSON array or CSV to insert multiple rows in a single
|
|
HTTP request. Note that using CSV requires less parsing on the server
|
|
and is **much faster**.
|
|
|
|
Example of CSV bulk insert. 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.
|
|
|
|
Example of JSON bulk insert. Send an array:
|
|
|
|
```HTTP
|
|
POST /people
|
|
[
|
|
{ "name": "J Doe", "age": 62, "height": 70 },
|
|
{ "name": "Janus", "age": 10, "height": 55 }
|
|
]
|
|
```
|
|
|
|
If you would like to get the full object back in the response to
|
|
your request, include the header `Prefer: return=representation`.
|
|
Chances are you only want certain information back, though, like
|
|
created ids. You can pass a `select` parameter to affect the shape
|
|
of the response (further documented in the [reading](/api/reading/)
|
|
page). For instance
|
|
|
|
```HTTP
|
|
POST /people?select=id
|
|
[...]
|
|
```
|
|
returns something like
|
|
```json
|
|
[ { "id": 1 }, { "id": 2 } ]
|
|
```
|
|
|
|
### 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=is.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>
|