API

API

AGRIDS stores map and vineyard data in FIWARE Orion using the NGSI-v2 entity API.

The OpenAPI document in this repository is:

• AGRIDS FIWARE NGSI-v2 OpenAPI JSON

Endpoint Summary

Environment	Endpoint pattern	Use when
Local deployment	http://localhost:1026/v2/entities	Running Orion directly with Docker Compose
Hosted secured deployment	https://<server>/v2_secure/entities?api_key=<API_KEY>	Your deployment includes an API-key/auth proxy

Note

The local Flask checkout does not implement /v2_secure or API-key generation. Those are deployment wrapper features.

Local Orion API

For a local deployment, use Orion directly:

http://localhost:1026/v2/entities

List entities:

curl "http://localhost:1026/v2/entities?limit=1000"

List all vine rows for a vineyard:

curl "http://localhost:1026/v2/entities?type=VineRow&q=vineyard_id==riseholme&limit=1000"

View one entity:

curl "http://localhost:1026/v2/entities/<entity_id>"

Orion returns a maximum of 20 entities by default. Add limit=<number> for larger queries. The maximum supported by Orion is commonly 1000.

Public Secure Endpoint Pattern

Some public AGRIDS deployments expose Orion through a secured endpoint and require an API key:

https://vista.zrok.lcas.group/v2_secure/entities?api_key=<API_KEY>

Filtered example:

https://vista.zrok.lcas.group/v2_secure/entities?type=VineRow&q=vineyard_id==riseholme&limit=1000&api_key=<API_KEY>

If running your own secured deployment, replace vista.zrok.lcas.group with your server name. API-key generation and user management depend on the public deployment wrapper; they are not implemented as local Flask routes in this checkout.

Create an Entity

Create entities with the standard Orion POST /v2/entities method:

curl -X POST "http://localhost:1026/v2/entities" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "example-test-001",
    "type": "Test",
    "text": {
      "type": "Text",
      "value": "hello"
    }
  }'

For a secured public endpoint, append ?api_key=<API_KEY> and include any HTTP authentication required by that deployment.

Update an Entity

Update attributes with PATCH /v2/entities/<entity_id>/attrs:

curl -X PATCH "http://localhost:1026/v2/entities/example-test-001/attrs" \
  -H "Content-Type: application/json" \
  -d '{
    "text": {
      "type": "Text",
      "value": "updated_hello"
    }
  }'

Delete an Entity

Delete an entity with:

curl -X DELETE "http://localhost:1026/v2/entities/example-test-001"

Filtering

AGRIDS uses standard Orion filters. Useful query parameters include:

• type=VineRow
• q=vineyard_id==riseholme
• limit=1000

Example:

curl "http://localhost:1026/v2/entities?type=Block&q=vineyard_id==riseholme&limit=1000"

For full filter syntax, see the FIWARE Orion filtering documentation.