API: Add v2 endpoints with query-parameter EIDs

docs/api.md

@@ -9,6 +9,8 @@ For routine same-host reads and writes, prefer `dp3 sh` or the generated `<APPNA
 
 There are several API endpoints:
 
+### v1 API (Original)
+
 - [`GET /`](#index): check if API is running (just returns `It works!` message)
 - [`POST /datapoints`](#insert-datapoints): insert datapoints into DP³
 - [`GET /entity/<entity_type>/get`](#get-entities): get current snapshots of entities of entity type
@@ -22,6 +24,27 @@ There are several API endpoints:
 - [`GET /entity/<entity_type>/_/distinct/<attr_id>`](#get-distinct-values): get distinct attribute values and their counts based on latest snapshots
 - [`DELETE /entity/<entity_type>/<entity_id>`](#delete-eid-data): delete entity data for given id
 - [`POST /entity/<entity_type>/<entity_id>/ttl`](#extend-ttls): extend TTLs of the specified entity
+
+**Note:** The v1 API has a limitation where Entity IDs (EIDs) containing `/` characters (e.g., IPv6 CIDR notation like `2001:db8:f00::/64`) cannot be accessed via the REST API because `/` is interpreted as a path separator. For such EIDs, use the v2 API below.
+
+### v2 API (Query-parameter EIDs)
+
+The v2 API addresses the limitation of EIDs containing special characters by passing the EID as a query parameter instead of in the URL path.
+
+- [`GET /v2/entity/<entity_type>/get`](#v2-get-entities): list entities (same as v1)
+- [`GET /v2/entity/<entity_type>/count`](#v2-count-entities): count entities (same as v1)
+- [`GET /v2/entity/<entity_type>/raw/get`](#v2-get-raw-datapoints): get raw datapoints (same as v1)
+- [`GET /v2/entity/<entity_type>/_/distinct/<attr_id>`](#v2-get-distinct-values): get distinct values (same as v1)
+- [`GET /v2/entity/<entity_type>/`](#v2-get-eid-data): get entity data with `?eid=X`
+- [`GET /v2/entity/<entity_type>/master`](#v2-get-master-record): get master record with `?eid=X`
+- [`GET /v2/entity/<entity_type>/snapshots`](#v2-get-snapshots): get snapshots with `?eid=X`
+- [`GET /v2/entity/<entity_type>/attr`](#v2-get-attr-value): get attribute with `?eid=X&attr=name`
+- [`POST /v2/entity/<entity_type>/attr`](#v2-set-attr-value): set attribute with `?eid=X&attr=name`
+- [`POST /v2/entity/<entity_type>/ttl`](#v2-extend-ttls): extend TTL with `?eid=X`
+- [`DELETE /v2/entity/<entity_type>/`](#v2-delete-eid-data): delete entity with `?eid=X`
+
+### Other Endpoints
+
 - [`GET /entities`](#entities): list entity configuration
 - [`GET /control/<action>`](#control): send a pre-defined action into execution queue.
 - [`GET /telemetry/sources_validity`](#source-validity): get timestamps of latest data from each source
@@ -760,3 +783,256 @@ Only queues belonging to the current DP³ application are returned.
   ]
 }
 ```
+
+---
+
+## v2 API: Query-Parameter EIDs
+
+The v2 API provides an alternative way to access entities where the Entity ID (EID) is passed as a query parameter instead of in the URL path. This allows EIDs containing special characters like `/` (e.g., IPv6 CIDR notation `2001:db8:f00::/64`).
+
+### Why v2 API?
+
+In the v1 API, EIDs are part of the URL path:
+```
+GET /entity/ipv6_64prefix/2001:db8:f00::/64/snapshots
+```
+
+This fails because `/64` is interpreted as a new path segment, causing a 404 error.
+
+In the v2 API, the EID is a query parameter:
+```
+GET /v2/entity/ipv6_64prefix/snapshots?eid=2001:db8:f00::/64
+```
+
+This works correctly because the entire EID value is passed as a query string. Query
+parameter values still need to be URL-encoded as usual; the examples below let `curl` handle
+encoding rather than constructing query strings manually.
+
+---
+
+### v2 Get Entities
+
+Same as v1 `/entity/{etype}/get`. See v1 documentation above.
+
+### v2 Count Entities
+
+Same as v1 `/entity/{etype}/count`. See v1 documentation above.
+
+### v2 Get Raw Datapoints
+
+Same as v1 `/entity/{etype}/raw/get`. See v1 documentation above.
+
+### v2 Get Distinct Values
+
+Same as v1 `/entity/{etype}/_/distinct/{attr}`. See v1 documentation above.
+
+---
+
+### v2 Get EID Data
+
+Get data of an entity identified by `etype` and `eid`.
+
+#### Request
+
+`GET /v2/entity/{etype}/?eid=<entity_id>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID (can contain special characters like `/`) | Yes |
+| `date_from` | Start date for filtering (ISO 8601) | No |
+| `date_to` | End date for filtering (ISO 8601) | No |
+
+#### Example
+
+```bash
+# IPv6 CIDR notation EID
+curl --get "http://localhost:8000/v2/entity/ipv6_64prefix/" \
+  --data-urlencode "eid=2001:db8:f00::/64"
+
+# Path-like EID
+curl --get "http://localhost:8000/v2/entity/user/" \
+  --data-urlencode "eid=admin/root"
+```
+
+#### Response
+
+**`200 OK`**: Same structure as v1 `/entity/{etype}/{eid}` response.
+
+---
+
+### v2 Get Master Record
+
+Get the master record of an entity.
+
+#### Request
+
+`GET /v2/entity/{etype}/master?eid=<entity_id>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+| `date_from` | Start date for filtering | No |
+| `date_to` | End date for filtering | No |
+
+#### Example
+
+```bash
+curl --get "http://localhost:8000/v2/entity/ipv6_64prefix/master" \
+  --data-urlencode "eid=2001:db8:f00::/64"
+```
+
+---
+
+### v2 Get Snapshots
+
+Get snapshot history of an entity.
+
+#### Request
+
+`GET /v2/entity/{etype}/snapshots?eid=<entity_id>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+| `date_from` | Start date for filtering | No |
+| `date_to` | End date for filtering | No |
+| `skip` | Number of snapshots to skip (pagination) | No, default=0 |
+| `limit` | Maximum snapshots to return (0=no limit) | No, default=0 |
+
+#### Example
+
+```bash
+curl --get "http://localhost:8000/v2/entity/ipv6_64prefix/snapshots" \
+  --data-urlencode "eid=2001:db8:f00::/64" \
+  --data-urlencode "limit=10"
+```
+
+---
+
+### v2 Get Attribute Value
+
+Get attribute value for an entity.
+
+#### Request
+
+`GET /v2/entity/{etype}/attr?eid=<entity_id>&attr=<attr_name>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+| `attr` | Attribute name | Yes |
+| `date_from` | Start date for history | No |
+| `date_to` | End date for history | No |
+
+#### Example
+
+```bash
+curl --get "http://localhost:8000/v2/entity/ipv6_64prefix/attr" \
+  --data-urlencode "eid=2001:db8:f00::/64" \
+  --data-urlencode "attr=network"
+```
+
+---
+
+### v2 Set Attribute Value
+
+Set attribute value for an entity.
+
+#### Request
+
+`POST /v2/entity/{etype}/attr?eid=<entity_id>&attr=<attr_name>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+| `attr` | Attribute name | Yes |
+
+#### Request Body
+
+```json
+{
+  "value": "new_value"
+}
+```
+
+#### Example
+
+```bash
+curl --request POST "http://localhost:8000/v2/entity/example/attr" \
+  --url-query "eid=test_id" \
+  --url-query "attr=hostname" \
+  --header "Content-Type: application/json" \
+  --data '{"value": "new_hostname"}'
+```
+
+---
+
+### v2 Extend TTLs
+
+Extend TTLs of an entity.
+
+#### Request
+
+`POST /v2/entity/{etype}/ttl?eid=<entity_id>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+
+#### Request Body
+
+```json
+{
+  "default": "2025-12-31T23:59:59Z"
+}
+```
+
+#### Example
+
+```bash
+curl --request POST "http://localhost:8000/v2/entity/example/ttl" \
+  --url-query "eid=test_id" \
+  --header "Content-Type: application/json" \
+  --data '{"default": "2025-12-31T23:59:59Z"}'
+```
+
+---
+
+### v2 Delete Entity Data
+
+Delete the master record and snapshots of an entity.
+
+#### Request
+
+`DELETE /v2/entity/{etype}/?eid=<entity_id>`
+
+#### Query Parameters
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `eid` | Entity ID | Yes |
+
+#### Example
+
+```bash
+curl --request DELETE "http://localhost:8000/v2/entity/example/" \
+  --url-query "eid=test_id"
+```
+
+---
+
+### v2 API Testing
+
+See [`tests/test_api/test_v2_api.py`](../tests/test_api/test_v2_api.py) for comprehensive test examples.

dp3/api/main.py

@@ -48,6 +48,7 @@ async def validation_exception_handler(request, exc):
 )
 
 # Register routers
+app.include_router(entity.v2_router, prefix="/v2/entity", tags=["Entity v2"])
 app.include_router(entity.router, prefix="/entity", tags=["Entity"])
 app.include_router(control.router, prefix="/control", tags=["Control"])
 app.include_router(telemetry.router, prefix="/telemetry", tags=["Telemetry"])