v6: documentation on PUT /clients/ is not complete

[jojost1]

Versions

• Pi-hole: v5.17.3-288-g760f903d
• AdminLTE: v5.19-700-gda7c0efb
• FTL: vDev-bffd2bd
  Branch is development-v6

Platform

• OS and version: Debian
• Platform: Raspberry Pi

Expected behavior

The API states the only fields are 'comment' and 'groups'. However, it looks like the web interface also sends a field 'client' (unclear to me what this is) and 'enabled', like this:

{"client":"00360032003a00390043003a00310034003a00450033003a00310035003a00330045","groups":[1],"comment":"Test Device","enabled":false}

Actual behavior / bug

Without a correct client field, it looks like Pi-hole creates a new client instead of updating an existing one. It's also unclear what the 'enabled' field means that the web interface sends (could just be a bug?).

Furthermore, the GET /clients endpoint also returns a 'name' property for a client which is undocumented as well. I'm not sure if this has to be send for PUT requests as well.

Additional context

This issue is about the new v6 API.

[jojost1]

Additionally I found out that a call to delete a client is also not working for me (while e.g. deleting a group works fine). It's throwing a 404.

The web interface seems to use /clients:batchDelete always, so I can't check what's going on.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Please comment or update this issue or it will be closed in 5 days.

[jojost1]

The issue is still there.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Please comment or update this issue or it will be closed in 5 days.

[jojost1]

I still have the issue

[DL6ER]

Sorry for this to have gone unnoticed for so long, I moved it into the correct repository now.

extra client field (PUT)

This is a left-over from API development, it isn't needed.

I'm not sure what you mean by

without the correct client field, it looks like Pi-hole creates a new client instead of updating an existing one.

The client to be modified has to be specified through the URI (and needs to be URI-encoded if that matters, e.g. for MAC addresses or IPv6 addresses : -> %3A )

A request may look like:

PUT https://pi.hole/api/clients/00%3A11%3A22%3A44%3A55%3A66

{"groups":[0],"comment":"ABC"}

which will edit the client 00:11:22:33:44:55 if it exists. I just confirmed this indeed works as expected and does not create a new client.

extra enabled field (PUT)

This is a copy-paste remnant from development as well and entirely ignored by the /clients endpoint

extra name field (GET)

This is a read-only field transmitted by the API in case it knows the host name connected too this IP/MAC address. It does not have to be sent in POST/PUT but is automatically populated by DNS data and contained in GET.

DELETE not working

Please check if you are correctly encoding the client (as above in no. 1), I can delete clients in a local test just fine.

Related changes

#1944

pi-hole/web#3016

[DL6ER]

The point you've mentioned have been fixed in the code. Feel free to reopen/comment if you find something we've talked about here not having been fixed.

[jojost1]

Got it working, thanks for the reply!