Custom DNS HTTP API Documentation


I have a Pi-hole in my house as well as a small Kubernetes cluster running on Pi 4Bs. I am thinking about implementing a Pi-hole provider for the external-dns project such that defining a public Service in Kubernetes will result in a DNS entry being added to my Pi-hole automatically. That would be super-convenient and it'd be a great reason to learn some Go.

I can see from this question that there is Telnet API documentation. I can also see this thread which is described as "full usage" on the AdminLTE GitHub page. In my case, it looks like I'm specifically interested in authentication and customdns.php, which doesn't seem to be covered in that docs thread.

Could I also ask how supported these APIs are? I don't see a versioning mechanism so I don't think there's any defense against breaking API changes?

Thanks a lot for any assistance!

They are about to reach end-of-life. We're going to replace them soon(ish) with a completely rewritten REST JSON-encoded API. It is about 30% feature complete by now (I'd say) and is active work-in-progress. The documentation is a bit lacking behind but will be self-hosted on the Pi-hole to ensure you always see the correct documentation for the version you have installed (it'll be available offline, too).

No PHP and external HTTP server will be needed. It all lives in FTL's branch new/http right now, but the API may still change substantially so do not consider it being stable in any way.

1 Like

Hi, thanks for the reply!

I don't mind waiting a while for the new version to stabilise. I see there's an OpenAPI spec too - I think this means I can generate a client rather than having to write one. Will the self-hosted documentation be the Swagger UI?

No, we tested a few things and Swagger UI seemed just the most widely known but has a lot of limitations as long as you don't go to their "pro" licensing (which would be very costly). We compared a few solutions and settled down on RaPi-Doc. It offers really a lot and is fully open-source and really free (not only free for some limited down feature set).

Check out if you want to see more.

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.