Document new PATCH and DELETE API operations (#126)

This commit is contained in:
Christopher C. Wells 2020-03-13 20:22:58 -07:00 committed by Christopher Charbonneau Wells
parent 76b7e90396
commit fbe15868f8
1 changed files with 69 additions and 0 deletions

View File

@ -31,6 +31,8 @@ guess work.
- [`GET` Method](#get-method)
- [`OPTIONS` Method](#options-method)
- [`POST` Method](#post-method)
- [`PATCH` Method](#patch-method)
- [`DELETE` Method](#delete-method)
- [Contributing](#contributing)
## Demo
@ -499,6 +501,28 @@ will return five diaper changes starting from the 10th diaper change entry:
Field-based filters for specific endpoints can be found the in the `filters`
field of the `OPTIONS` response for specific endpoints.
Single entries can also be retrieved by adding the ID (or in the case of a
Child entry, the slug) of a particular entry:
curl -X GET https://[...]/api/children/gregory-hill/ -H 'Authorization: Token [...]'
{
"id":3,
"first_name":"Gregory",
"last_name":"Hill",
"birth_date":"2020-02-11",
"slug":"gregory-hill",
"picture":null
}
curl -X GET https://[...]/api/sleep/1/ -H 'Authorization: Token [...]'
{
"id":480,
"child":3,
"start":"2020-03-12T21:25:28.916016-07:00",
"end":"2020-03-13T01:34:28.916016-07:00",
"duration":"04:09:00",
"nap":false
}
#### Response
Returns JSON data in the response body in the following format:
@ -515,6 +539,9 @@ Returns JSON data in the response body in the following format:
- `previous`: URL for the previous set of results.
- `results`: An array of the results of the request.
For single entries, returns JSON data in the response body keyed by model field
names. This will vary between models.
### `OPTIONS` Method
#### Request
@ -576,6 +603,48 @@ error details if errors exist. Errors are keyed by either the field in error or
the general string `non_field_errors` (usually when validation involves
multiple fields).
### `PATCH` Method
#### Request
To update existing entries, send a `PATCH` request to the single entry endpoint
for the entry to be updated. The `Content-Type` header for `PATCH` request must
be set to `application/json`. For example, to update a Diaper Change entry with
ID 947 to indicate a "wet" diaper only:
curl -X PATCH \
-H 'Authorization: Token [...]' \
-H "Content-Type: application/json" \
-d '{"wet":1, "solid":0}' \
https://[...]/api/changes/947/
Regular sanity checks will be performed on relevant data. See the `OPTIONS`
response for a particular endpoint for details on required fields and data
formats.
#### Response
Returns JSON data in the response body describing the added/updated instance or
error details if errors exist. Errors are keyed by either the field in error or
the general string `non_field_errors` (usually when validation involves
multiple fields).
### `DELETE` Method
#### Request
To delete an existing entry, send a `DELETE` request to the single entry
endpoint to be deleted. For example, to delete a Diaper Change entry with ID
947:
curl -X DELETE https://[...]/api/changes/947/ -H 'Authorization: Token [...]'
#### Response
Returns an empty response with HTTP status code `204` on success, or a JSON
encoded error detail if an error occurred (e.g. `{"detail":"Not found."}` if
the requested ID does not exist).
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed