diff --git a/docs/client.md b/docs/client.md index 2c5f051..ab816c0 100644 --- a/docs/client.md +++ b/docs/client.md @@ -1,21 +1,21 @@ -# Client methods for farmOS 2.x +# Client methods for farmOS ## Resources -The farmOS 2.x API uses the JSON:API module included with Drupal core, which +The farmOS API uses the JSON:API module included with Drupal core, which follows the [JSON:API](https://jsonapi.org/) specification for defining API -resources. More info on the farmOS 2.x api -[here](https://farmos.org/development/api/). +resources. More information on the farmOS api see the +[farmOS API documentation](https://farmos.org/development/api/). -Any resource on a farmOS 2.x server can be interacted via the +Any resource on a farmOS server can be interacted via the `farm_client.resource` namespace in the farmOS.py client. The following methods are available: -- `resource.get()`: Perform a GET request. Returns a single page of resources. -- `resource.get_id()`: Perform a GET request for a single resource. -- `resource.iterate()`: Returns a Python iterator that can be used to GET +- `resource.get(entity_type, bundle, params)`: Perform a GET request. Returns a single page of resources. +- `resource.get_id(entity_type, bundle, id)`: Perform a GET request for a single resource. +- `resource.iterate(entity_type, bundle, params)`: Returns a Python iterator that can be used to GET multiple pages of resources. -- `resource.send()`: Perform a POST or PATCH request. -- `resource.delete()`: Perform a DELETE request. +- `resource.send(entity_type, bundle, payload)`: Perform a POST or PATCH request. +- `resource.delete(entity_type, bundle, id)`: Perform a DELETE request. Each of these methods requires the JSON:API resource type identifier in order to determine the correct URL of the resource. Because the Drupal JSON:API module @@ -38,86 +38,18 @@ provided, it assumed the entity has no bundles: response = farm_client.resource.get('user') ``` -Similarly, Logs, Assets and Terms have these same methods available within -their own namespace and only require the `bundle` parameter. +For convenience, Logs, Assets and Terms have these same methods available +within their own namespace and only require the `bundle` parameter. To +interact with Logs: +- `farm_client.log.get('observation')` +- `farm_client.log.get_id('observation', log_id)` +- `farm_client.log.iterate('observation')'` +- `farm_client.log.send('observation', log_data)` +- `farm_client.log.delete('observation', log_id)` -### Logs +### Resource methods -A log is any type of event that occurs on the farm, from a planting to a -harvest to just a general observation. - -Methods for getting, sending and deleting logs are namespaced on the `farm.log` -property. - -The four default log types are: - -- `activity` -- `harvest` -- `input` -- `observation` - -Other log types may be provided by add-on modules in farmOS. - -#### `.iterate()` - -```python -# Get all observation logs. -logs = list(farm_client.log.iterate('observation')) - -# Filter to 'done' logs. -filters = farm_client.filter('status', 'done') -done_observations = list(farm_client.log.iterate('observation', params=filters)) -``` - -#### `.get()` and `.get_id()` - -```python -# Get one page of observation logs. -response = farm_client.log.get('observation') - -# Filter to 'done' logs. -filters = farm_client.filter('status', 'done') -response = farm_client.log.get('observation', params=filters) - -# Get observation log by ID. -id = 'b9e8c253-a3c1-4af4-b2c8-7f201dc2b046' -log = farm_client.log.get_id('observation', id) -``` - -#### `.send()` - -Send can be used to create a new log, or if the `id` property is included, to -update an existing log: - -```python - -# Create observation log -observation_log = { - "attributes": { - "name": "My Great Observation", - "status": "pending", - "notes": "Some notes" - } -} -log = farm_client.log.send('observation', observation_log) - -# Update log. -done = { - 'id': 'b9e8c253-a3c1-4af4-b2c8-7f201dc2b046', - "attributes": { - "status": "done", - } -} -log = farm_client.log.send('observation', done) -``` - -#### `.delete()` - -```python -farm_client.log.delete('observation', 'b9e8c253-a3c1-4af4-b2c8-7f201dc2b046') -``` - -### Assets +Below are examples interacting with assets. Assets are any piece of property or durable good that belongs to the farm, such as a piece of equipment, a specific crop, or an animal. @@ -125,7 +57,7 @@ as a piece of equipment, a specific crop, or an animal. Methods for getting, sending and deleting assets are namespaced on the `farm.asset` property. -### `.iterate()` +#### `.iterate()` ```python # Get all animal assets. @@ -151,18 +83,6 @@ response = farm_client.asset.get('animal', params=filters) response = farm_client.asset.get_id('animal', 'b9e8c253-a3c1-4af4-b2c8-7f201dc2b046') ``` -Some common asset types include: - -- `land` -- `structure` -- `water` -- `animal` -- `plant` -- `equipment` -- `sensor` - -Other asset types may be provided by add-on modules in farmOS. - #### `.send()` Send can be used to create a new asset, or if the `id` property is included, to update an existing asset: @@ -202,46 +122,4 @@ response = farm_client.asset.send('plant', update) ```python farm_client.asset.delete('planting', "b9e8c253-a3c1-4af4-b2c8-7f201dc2b046") -``` - -### Taxonomy Terms - -farmOS allows farmers to build vocabularies of terms for various categorization -purposes. These are referred to as "taxonomies" in farmOS (and Drupal), although -"vocabulary" is sometimes used interchangeably. - -Some things that are represented as taxonomy terms include quantity units, -crops/varieties, animal species/breeds, input materials, and log categories. - -### `.iterate()` - -```python -# Get all plant_type terms. -plant_types = list(farm_client.term.iterate('plant')) -``` - -#### `.get()` and `.get_id()` - -```python - -# Get one page of plant_type terms -response = farm_client.term.get('plant_type') - -# Get a specific term -response = farm_client.term.get_id('plant_type', "a260441b-2553-4715-83ee-3ac08a6b85f0") -``` - -#### `.send()` - -Send can be used to create a new taxonomy term, or if the `id` property is included, to update an existing term: - -```python -# Create a new plant type. -response = farm_client.term.send('plant_type', {"attributes": {"name": "Corn"}}) -``` - -#### `.delete()` - -```python -farm_client.term.delete('plant_type', "a260441b-2553-4715-83ee-3ac08a6b85f0") -``` +``` \ No newline at end of file