REST API
Once the FarmVibes.AI cluster is up and running, you can interact with it using the REST API, which provides a set of endpoints that allow you to list and describe workflows, as well as manage workflow runs. The REST API is available at the URL and port specified during cluster creation, and its address is printed in the terminal once the setup is complete. You can also check the address by running the following command in the terminal:
$ farmvibes-ai <local | remote> status
2024-01-01 00:00:00,000 - INFO - Cluster farmvibes-ai-username is running with 1 servers and 0 agents.
2024-01-01 00:00:00,001 - INFO - Service url is http://ip.address:port
Interacting with the API
The API is accessible from the FarmVibes.AI Python client, which provides an interface to interact with the cluster, list workflows, and manage workflow runs.
Alternativelly, interacting with the API can be done using any tool that can send HTTP requests, such as curl or Bruno.
For example, to list the available workflows, you can use the following command:
$ curl -X GET http://localhost:31108/v0/workflows
Which will return the following list:
["helloworld","farm_ai/land_degradation/landsat_ndvi_trend","farm_ai/land_degradation/ndvi_linear_trend", ...]
For submiting a run of a specific workflow, we need to pass a JSON with the run configuration
(i.e., workflow name, input geometry and time range, workflow parameters, etc) as the body of the
request. For example, we can use the following command to create a helloworld workflow run:
$ curl -X POST -H "Content-Type: application/json" -d <JSON>
Replacing the body of the request <JSON> with the following:
{
"name": "Hello!",
"workflow": "helloworld",
"parameters": null,
"user_input": {
"start_date": "2020-05-01T00:00:00",
"end_date": "2020-05-05T00:00:00",
"geojson": {
"features": [
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-119.14896203939314,
46.51578909859286
],
[
-119.14896203939314,
46.37578909859286
],
[
-119.28896203939313,
46.37578909859286
],
[
-119.28896203939313,
46.51578909859286
],
[
-119.14896203939314,
46.51578909859286
]
]
]
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
}
}
To help in understanding the expected format and structure of the json in our requests, we provide in
our Python client the _form_payload method (vibe_core.client.FarmvibesAiClient._form_payload) that can be used to
generate the request payload for a given run configuration. For example, the following code could
be used to obtain the json above for the helloworld workflow:
from vibe_core.client import get_default_vibe_client
import shapely.geometry as shpg
from datetime import datetime
client = get_default_vibe_client()
geom = shpg.Point(-119.21896203939313, 46.44578909859286).buffer(.07, cap_style=3)
time_range = (datetime(2020, 5, 1), datetime(2020, 5, 5))
payload = client._form_payload("helloworld", None, geom, time_range, None,"Hello!")
Another example, considering the farm_ai/segmentation/segment_s2 workflow run submited in the
Sentinel-2 Segmentation notebook, would be:
payload = client._form_payload("farm_ai/segmentation/segment_s2", None, None, None, {"user_input": roi_time_range, "prompts": geom_collection},"SAM segmentation")
Which would generate the following json:
{
"name": "SAM segmentation",
"workflow": "farm_ai/segmentation/segment_s2",
"parameters": null,
"user_input": {
"user_input": {
"type": "Feature",
"stac_version": "1.0.0",
"id": "f6465ad0-5e01-4792-ad99-a0bd240c1e7d",
"properties": {
"start_datetime": "2020-05-01T00:00:00+00:00",
"end_datetime": "2020-05-05T00:00:00+00:00",
"datetime": "2020-05-01T00:00:00Z"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-119.14896203939314,
46.51578909859286
],
[
-119.14896203939314,
46.37578909859286
],
[
-119.28896203939313,
46.37578909859286
],
[
-119.28896203939313,
46.51578909859286
],
[
-119.14896203939314,
46.51578909859286
]
]
]
},
"links": [],
"assets": {},
"bbox": [
-119.28896203939313,
46.37578909859286,
-119.14896203939314,
46.51578909859286
],
"stac_extensions": [],
"terravibes_data_type": "DataVibe"
},
"prompts": {
"type": "Feature",
"stac_version": "1.0.0",
"id": "geo_734c6441-cb25-4c40-8204-6b7286f24bb9",
"properties": {
"urls": [
"/mnt/734c6441-cb25-4c40-8204-6b7286f24bb9_geometry_collection.geojson"
],
"start_datetime": "2020-05-01T00:00:00+00:00",
"end_datetime": "2020-05-05T00:00:00+00:00",
"datetime": "2020-05-01T00:00:00Z"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-119.14896203939314,
46.51578909859286
],
[
-119.14896203939314,
46.37578909859286
],
[
-119.28896203939313,
46.37578909859286
],
[
-119.28896203939313,
46.51578909859286
],
[
-119.14896203939314,
46.51578909859286
]
]
]
},
"links": [],
"assets": {},
"bbox": [
-119.28896203939313,
46.37578909859286,
-119.14896203939314,
46.51578909859286
],
"stac_extensions": [],
"terravibes_data_type": "ExternalReferenceList"
}
}
}
For more information about the _form_payload method, please refer to the FarmVibes.AI Python client documentation.
Endpoints
We provide below a list of the available endpoints and their descriptions.
- GET /
Terravibes Root
Root endpoint.
Example request:
GET / HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "message": "string", "id": "string", "location": "string" }
- GET /system-metrics
Terravibes Metrics
Get system metrics, including CPU usage, memory usage, and storage disk space.
Example request:
GET /system-metrics HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "load_avg": [ 1.0 ], "cpu_usage": 1.0, "free_mem": 1, "used_mem": 1, "total_mem": 1, "disk_free": 1 }
- GET /workflows
Terravibes List Workflows
List all workflows available in FarmVibes.AI.
Example request:
GET /workflows HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
- GET /workflows/{workflow}
Terravibes Describe Workflow
Get a workflow by name, either as JSON description, or YAML graph implementation.
- Parameters:
workflow (string) – The name of the workflow to be described.
- Query Parameters:
return_format (string) – The format to return the workflow in [description, yaml].
Example request:
GET /workflows/{workflow} HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- GET /runs
Terravibes List Runs
List all the workflow runs currently in the system.
- Query Parameters:
ids (array) – The list of run IDs to retrieve. If not provided, all runs are returned.
page (integer) – The page number to retrieve.
items (integer) – The number of items per page.
fields (array) – Fields to return alongside each run id. If not provided, only run ids are returned.
Example request:
GET /runs HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- POST /runs
Terravibes Create Run
Submit a new workflow run.
Example request:
POST /runs HTTP/1.1 Host: example.com Content-Type: application/json { "name": "example workflow run for sample region", "workflow": "helloworld", "parameters": {}, "user_input": { "start_date": "2021-02-02T00:00:00Z", "end_date": "2021-08-02T00:00:00Z", "geojson": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ [ [ -88.068487, 37.058836 ], [ -88.036059, 37.048687 ], [ -88.012895, 37.068984 ], [ -88.026622, 37.085711 ], [ -88.062482, 37.081461 ], [ -88.068487, 37.058836 ] ] ] } } ] } } }
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- GET /runs/{run_id}
Terravibes Describe Run
Get information of a specific run.
- Parameters:
run_id (string) – The ID of the workflow execution to get.
Example request:
GET /runs/{run_id} HTTP/1.1 Host: example.com
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- DELETE /runs/{run_id}
Terravibes Delete Run
Delete data associated with a workflow run (if not shared by other runs).
For a detailed overview on how data is managed in FarmVibes.AI, please refer to the documentation.
- Parameters:
run_id (string) – The ID of the workflow run to delete.
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- POST /runs/{run_id}/cancel
Terravibes Cancel Run
Cancel a workflow run.
- Parameters:
run_id (string) – The ID of the workflow run to cancel.
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }
- POST /runs/{run_id}/resubmit
Terravibes Resubmit Run
Resubmit a workflow run.
- Parameters:
run_id (string) – The ID of the workflow run to resubmit.
- Status Codes:
200 OK –
Successful Response
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
Validation Error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": [ { "loc": [ "string", 1 ], "msg": "string", "type": "string" } ] }