OpenAPI specs

Configuration
1

Hi everyone, I’m searching for the home-assitant openapi specs. I can’t find anything related. Do you know if are available somewhere?

Thanks in advance!

2 Likes
2

This is not a feature request. Please edit and recategorize your post

HAs deevelper docs are all here

3

Sure, could you please suggest the new category?

I’m not searching for docs (which I’m already aware of) but for openapi spec instead that doesn’t seems to be available anywhere.
It could be a feature request as it should come out with every API change and may allow developers to build clients programmatically.

4

I can’t even find any indication that HA’s API is OpenAPI? As far as I can tell, devices should implement OpenAPI so HA integrations can connect to them easily and not the other way around? But I may very well be mistaking.

Do you have any reference somewhere that suggests otherwise? And if HA’s API is not OpenAPI but there is good reason for that to change, then maybe this is a feature request indeed.

5

@Edwin_D I wasn’t very specific, I apologize.
OpenAPI is just a standard to describe the APIs, with this specs It’s possible to auto-generate client code (and not only) to interact with the endpoints. I’m not building a device interface I instead would like to interact with HA using the available APIs.

6

I understood that, but your question seems to assume HA’s API follows the OpenAPI specs, and I don’t see an indication that they do. Is there anything you found that suggests it does, or might it be that you searching for something that isn’t there to begin with? The only thing I found is Home Assistant integrations for OpenAPI supporting devices.

7

Exactly, I’m searching for something that is not currently there. That’s why I opened a feature request. It may provide great added value for who want to interact with HA APIs without the needed of writing each request by hand and maybe to enforce the contract between client and server.

8

Is this useful to you? REST API | Home Assistant Developer Docs

9

@raelix is asking for a JSON file that describes the HomeAssistant API in OpenAPI format. This can be useful for describing an API for an application gateway, or for interfacing another system with the home assistant API in the context of a service oriented architecture.

It would be a very nice feature for HA to offer this, especially if it could be generated alongside the API documentation.

From Wikipedia: “The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services”

1 Like
10

I think offering an OpenAPI (ideally automatically generated) is a good practice, specially for automation.

Also it can be used for AI models to provide a list of tools to use

1 Like
11

While it’s trivial to make an HTTP request, unmarshall the JSON data, and process it in Python, it’s not so trivial in other languages like C, C++, Go, et al. Having the OpenAPI Spec readily available allows authors of clients to automatically build clients for every endpoint you offer and adapt to changes quickly.

Please do whatever necessary to generate an OpenAPI-compliant spec with each of your releases.