OpenPlantbook-client

This is repository for Open Plantbook API sample clients.

Requirements

In order to use this API you need to login to Open Plantbook web UI at https://open.plantbook.io and generate API credentials. The credentials are client_id and client_secret. API authentication implements OAuth2 standard Client Credentials Grant flow.

WebUI and API Release notes:

version 1.03 (26 December 2020)

Major update:

Ability to add new and edit existing plants via API calls. (not UI yet)

Now user can update existing plant or create new one. There are 2 databases: user specific database (user's context) and main database (public).

All modifications of plants (new, existing) are only visible for the user who have modified them. Later, moderator can merge these modifications into main public database.
A modification of an existing plant creates a "shadow" or clone of the plant in the user context.
Once a plant has been updated, the user can only see this updated (shadow) version of the plant but not public version of it.
Newly created plants are only available to the user who created them until a moderator merges them into a main database.
It is not possible to create plant which already exists in a main DB. It can only be updated with API update call.
New or updated plants can be deleted from user context.
Once updated existing plant is deleted from user context (user's version of existing plant), the user can again retrieve a public version of the plant from main database.

3 new api calls are available:

For examples see examples section and Postman collection within repository and also public Postman collection here :

api/v1/plant/create Method: POST

Create new plant. All omitted non-mandatory attributes will have null value.

Mandatory attributes:
<display_pid> - Scientific name of the plant. Based on this attribute <pid> (Plant ID) attribute will be automatically generated by lowering case of this attribute.
E.g: <display_pid>="Tomato Red" will result in <pid>="tomato red". See postman example for details.

Returns:
201 - Successfully created.
409 - Plant already exists either in user DB or main DB.
400 - Malformed request e.g. if a mandatory attribute is not provided.

api/v1/plant/update Method: PATCH

Method updates either plant in a specific user's context or a plant from main DB by cloning the plant from main DB into user context and then applying requested changes to user profile's plant. Supports PATCH (partial update - updates only provided attributes), PUT is not supported

Mandatory attributes:
<pid> - Plant ID - unique plant identifier. Case SENSITIVE!

Returns:
200 - Successfully updated.
404 - Plant neither exist in user DB nor in main DB.
400 - Malformed request e.g. if a mandatory attribute is not provided.

api/v1/plant/delete Method: DELETE

Delete plant from user's context only. Plants cannot be removed from main DB.

Mandatory attributes:
<pid> - Plant ID - unique plant identifier. Case SENSITIVE!

Return:
204 - Successfully deleted.
404 - Plant does not exist in user DB.
400 - Malformed request e.g. if a mandatory attribute is not provided.

Known issue with DELETE: It does not handle omitted mandtory attributes correctly and always return 404 Not Found even if is absent. Will be fixed in next version.

version 1.02

Introduction of Plant images feature. api/v1/plant/detail/ endpoint returns Plant's image URL as image_url JSON string field.
Web UI is generally available for guests. Guests can search Plant DB but to get API key and plants details Signing in is required.

version 1.01

Browse-DB feature in WebUI so it is possible to search plants available in DB.
Small UI clean-ups

version 1.0

Breaking changes in comparison with 1.0-RC:

Removed api/v1/plant/detail/{id}/ endpoint
Removed "id" from responses
Now to get plant details use api/v1/plant/detail/{pid} endpoint.

Client Release notes:

version 1.0

Updated Postman collection:
- built-in variables for easier use (See variables specific to the Collection)
- "Get token" call now extracts and updates {{access_token}} value automatically (no need to copy/paste)
Added Python client by @Olen (https://github.com/Olen). Thanks and Kudos! The client is a step for Home-assistant.io integration and this is why it is a bit overcomplicated.

Integrations

home-assistant integration. Plant Monitor component and PlantCard which leverage the component. Discussion of HASS forum here.

Usage

The easiest way to get familiar with API is to use Browsable API within Web UI. The link can be found within Docs section. Alternatively, you can use excellent and easy tool - Postman. Postman collection can be found in corresponding folder of this repository. You need to install free Postman API tool: https://www.postman.com/ then import the collection.

Examples using CURL.

Retrieve plant:

Get API credentials from Web UI.
Get access token using API credentials.

curl --request POST 'https://open.plantbook.io/api/v1/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=string_client_id_from_UI' \
--form 'client_secret=string_client_secret_from_UI'

Response will be:

{
    "access_token": "token_string",
    "expires_in": 2629800,
    "token_type": "Bearer",
    "scope": "read"
}

This is token to access API. It will expire in 2629800 seconds = 1 month. It is ok to get a new token everytime. We will need "token_string" at next step.

Make a Plant Search API call with 'Bearer Token' HTTP header: Query parameter ?alias= is required.

curl --request GET 'https://open.plantbook.io/api/v1/plant/search?alias=acanthus%20ilicifolius' \
--header 'Authorization: Bearer token_string'

From the response, you can to get Plant Id (pid) in order to get the plant details.

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "pid": "acanthus ilicifolius",
            "display_pid": "Acanthus ilicifolius",
            "alias": "acanthus ilicifolius"
        },
        {
            "pid": "acanthus spinosus",
            "display_pid": "Acanthus spinosus",
            "alias": "acanthus ilicifolius"
        }
    ]
}

From previous step, take "pid" value of the desired plant and get the plant details with Bearer Token.

curl --request GET 'https://open.plantbook.io/api/v1/plant/detail/acanthus ilicifolius/' \
--header 'Authorization: Bearer token_string'

{
    "pid": "acanthus ilicifolius",
    "display_pid": "Acanthus ilicifolius",
    "alias": "acanthus ilicifolius",
    "max_light_mmol": 2500,
    "min_light_mmol": 1200,
    "max_light_lux": 6000,
    "min_light_lux": 1500,
    "max_temp": 32,
    "min_temp": 10,
    "max_env_humid": 80,
    "min_env_humid": 30,
    "max_soil_moist": 60,
    "min_soil_moist": 15,
    "max_soil_ec": 2000,
    "min_soil_ec": 350,
    "image_url": "https://example.com/n/sdpo/b/plant-img/o/acanthus%20ilicifolius.jpg"
}

Plant modifications example:

Create new plant:

curl --request POST 'http://open.plantbook.io/api/v1/plant/create' \
--header 'Authorization: Bearer token_string' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_pid": "Solanum lycopersicum",
    "alias": "Tomato",
    "max_light_mmol": 7600,
    "min_light_mmol": 3200,
    "max_light_lux": 55000,
    "min_light_lux": 3000,
    "max_temp": 33,
    "min_temp": 12,
    "max_env_humid": 80,
    "min_env_humid": 15,
    "max_soil_moist": 60,
    "min_soil_moist": 20,
    "max_soil_ec": 2000,
    "min_soil_ec": 350
}'

Response:

{
    "pid": "solanum lycopersicum",
    "display_pid": "Solanum lycopersicum",
    "alias": "Tomato",
    "max_light_mmol": 7600,
    "min_light_mmol": 3200,
    "max_light_lux": 55000,
    "min_light_lux": 3000,
    "max_temp": 33,
    "min_temp": 12,
    "max_env_humid": 80,
    "min_env_humid": 15,
    "max_soil_moist": 60,
    "min_soil_moist": 20,
    "max_soil_ec": 2000,
    "min_soil_ec": 350,
    "image_url": "https://objectstorage.ap-sydney-1.oraclecloud.com/n/sdyd5yr3jypo/b/plant-img/o/solanum%20lycopersicum.jpg"
}

Take pid value (not display_name)

Update this plant:

curl --request PATCH 'http://open.plantbook.io/api/v1/plant/update' \
--header 'Authorization: Bearer token_string' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pid": "solanum lycopersicum",
    "max_light_mmol": 1111,
    "min_light_mmol": 2222,
    "max_light_lux": 4444,
    "min_light_lux": 3333,
    "max_temp": 66,
    "min_temp": 55
}'

Response:

{
    "pid": "solanum lycopersicum",
    "display_pid": "Solanum lycopersicum",
    "alias": "Tomato",
    "max_light_mmol": 1111,
    "min_light_mmol": 2222,
    "max_light_lux": 4444,
    "min_light_lux": 3333,
    "max_temp": 66,
    "min_temp": 55,
    "max_env_humid": 80,
    "min_env_humid": 15,
    "max_soil_moist": 60,
    "min_soil_moist": 20,
    "max_soil_ec": 2000,
    "min_soil_ec": 350,
    "image_url": "https://objectstorage.ap-sydney-1.oraclecloud.com/n/sdyd5yr3jypo/b/plant-img/o/solanum%20lycopersicum.jpg"
}

Delete the plant:

curl --request DELETE 'http://open.plantbook.io/api/v1/plant/delete' \
--header 'Authorization: Bearer token_string' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pid": "solanum lycopersicum"
}'

Response:

Status: 204 No content

sickleper/OpenPlantbook-client

OpenPlantbook-client

Requirements

WebUI and API Release notes:

version 1.03 (26 December 2020)

api/v1/plant/create Method: POST

api/v1/plant/update Method: PATCH

api/v1/plant/delete Method: DELETE

version 1.02

version 1.01

version 1.0

Client Release notes:

version 1.0

Integrations

Usage

Examples using CURL.

Retrieve plant:

Plant modifications example: