Response Schema

[jcubit]

Hi there!

Where can I find the response schema for the different endpoints Bao/Vault offers, e.g. for auth/approle/login ?
The OpenAPI specification from /sys/internal/specs/ doesn't seem to include details about the structure of the response — specifically, the data field is not defined. The request are defined though. Is there another source or documentation where I can find the full response schema for all the endpoints? I know the general structure is something like

request_id: String

lease_id: String

renewable: Boolean

lease_duration: Int?

data: DataObject

wrap_info: WrapInfoObject

warnings: array of strings

auth: AuthObject

mount_type: String

Thank you in advance for any pointers here

[cipherboy]

Hey @jcubit -- OpenAPI schemas are definitely something that is a short coming at the moment. If you want to start improving that (and maybe contribute semgrep rules), that'd be very much appreciated.

To answer your question of where they actually are, bao path-help ... and the API docs are the best resources: https://openbao.org/api-docs/auth/approle/#login-with-approle

The auth structure may be less well defined (outside of code), which seems like an oversight worth correcting itself. Want to file an issue or PR about that one?

[jcubit]

Hi Alex! (@cipherboy) Thanks for your prompt reply and kind answer.

I'm actually developing a swift client for OpenBao and HashiCorp Vault, VaultCourier, which runs on Linux and macOS. It's driven by an OpenAPI specification that I'm writing with Pkl; the repository for vault-courier-pkl can be found here. The later approach to write the specification with Pkl has a number of advantages, for example:

1. It can be statically verified, and the output can be in either json or yaml
2. We can write the OpenAPI document in a modular way. This will be important if the OpenBao API diverges from the HashiCorp Vault API in the future. Perhaps there are already some important differences that I am not yet aware of (I'd be interested to know if that's already the case). I have just noticed some minor differences in responses, such as the absence of the 'mount_type' field in some OpenBao responses, but this is not critical information for those endpoints.
3. Other languages could use the specification to write their own clients.

The auth structure may be less well defined (outside of code), which seems like an oversight worth correcting itself. Want to file an issue or PR about that one?

bao path-helpis quite useful for the request types. However, as you noticed the response structure is not defined. Knowing this would help a lot with writing the spec, as I am not 100% sure if some fields are required or not. Could you perhaps give me a reference to where it is defined in the code? I don't know Go, but perhaps I can identify the required response fields. I will file an issue to collect the findings.

One can of course define in the OpenAPI arbitrary objects in the response, but that makes the decoding not only expensive at runtime, and it also makes the API more cumbersome to work with because it adds unnecessary checks and duplicate code.

I am interested in learning more about OpenBao and asking questions. Is there a channel like Discord, slack or a forum where I can ask quick questions?

Cheers,
Javier

[cipherboy]

@jcubit Check out https://github.com/orgs/openbao/discussions/656 for some context -- one of the issues with OpenAPI schemas is that there is no ability to add custom HTTP verbs (like LIST and SCAN). We support that, via GET with query parameters, but I don't know how we'd split that into separate operations that all live on the same API endpoint (KVv2 is probably the worst, supporting READ, SCAN, and LIST operations on a single endpoint that all resolve to GET).

#339 and #41 also in general have discussed OpenAPI and its usage.

[jcubit]

Found the Matrix channels :-)

[evil0606]

Hi, I'm trying to use the OpenApi spec on a Java project. Has there been any evolution on this subject please ?

Is the only solution available right now is using the Vault API as done in the Java example ?

Thank you