Update: OpenAPI Specification Improvements

[wwerner]

Hey folks,

we want to improve our API specifications for better client code generation.
This entails

• Adding operationIds to all operations
• Changing endpoint tags to better reflect the domain object they operate on
• Probably add some extension elements like x-operation-group to structure clients more efficiently
• Change the securityScheme to be used for both token and bearer auth.

In case you already use the specifications for client code generation, this might impact you: You likely depend on operation/function names your code generator created as default. So, before we break anything, we wanted to get in touch.

@external-developers, please let us know how you use the specifications and get in touch if you have any concerns!

I use the OpenAPI specifications …

• for generating API models
• for generating client operations
• not for code generation

[pierre]

That would be great!! We generate models from the specs, and would like to play around with generating a client as well.

[wwerner]

Hey everyone,

we went ahead with the first batch of changes, adding operationIds and changing the securityScheme.

The change log as all the details.

gridX API Changelog

Changelog 2025-02-17T10:13:59.951Z GET /account api operation id ‘getAuthenticatedAccount’ was added the endpoint scheme security ‘HeaderAuth’ was added to the API the endpoint scheme security ‘BearerAuth’ was removed from the API PATCH /account api operation id ‘updateAuthenticatedAccount’ was added the endpoint scheme security ‘HeaderAuth’ was added to the API the endpoint scheme security ‘BearerAuth’ was removed from the API GET /account/market-prices/{platform} api operation id ‘listMar…

[eon.stangl.external]

Good job. The operation IDs help a lot.

Before: client.postAccountsByAccountIdSystems( /* ... */)
After: client.assignSystemToAccount( /* ... */)

(TypeScript, “Hey API” client)

[wwerner]

And the next batch is out

You can now use both Bearer and long lived personal API Tokens for authorization. Previously, only Bearer authentication was supported, requiring users to frequently re-enter their Bearer token.

The change is already active for the gridX API and DER API documentation.

[!warning]
Previously, entering the Bearer prefix was not required. It now is; only entering the token will no longer work.