OpenAPI specification of admin APIv1 #672
No reviewers
Labels
No labels
action
check-aws
action
discussion-needed
action
for-external-contributors
action
for-newcomers
action
more-info-needed
action
need-funding
action
triage-required
kind
correctness
kind
ideas
kind
improvement
kind
performance
kind
testing
kind
usability
kind
wrong-behavior
prio
critical
prio
low
scope
admin-api
scope
background-healing
scope
build
scope
documentation
scope
k8s
scope
layout
scope
metadata
scope
ops
scope
rpc
scope
s3-api
scope
security
scope
telemetry
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference: Deuxfleurs/garage#672
Loading…
Reference in a new issue
No description provided.
Delete branch "api-v1"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Changed endpoint:
id, prev the key of the map (NodeNetworkInfo)Regenerating SDK:
Testing SDK:
GetClusterHealth
Pre-release
Update the doc:
Fixes #671.
The Python OpenAPI generator generates malformed URL on the SearchKey endpoint:
Expected:
?search=openapi&showSecretKey=TrueGot:
?search=openapi?showSecretKey=True(the 2nd question marks must be an ampersand)Edit: fixed in multiple iterations:
As I created a new file instead of patching v0, it's not possible to see from Gitea interface what changed. This URL shows the difference: diff open api spec
@ -0,0 +410,4 @@Delete a key from the cluster. Its access will be removed from all the buckets. Buckets are not automatically deleted and can be dangling. You should manually delete them before.parameters:- name: access_keyin: pathThanks for the super fast response on #671! Updated my fork of the terraform provider but can't delete a key (with the golang sdk).
It issues a request to
DELETE /v1/keywithout anidquery string parameter (which i think the endpoint consumes), and here it says it needs to go on the path, but there's no{access_key}in there. Should this bename: id, in: query?Indeed you're right.
Should be fixed now.
Discovered a new issue: capacity must be tagged as int64. Fixing the SDK...
12ee23f75ato9f1043586cCurrent commits to test:
Still missing:
Should we merge now, or are we waiting for something ?
Have you seen #671 (comment) ?
Discovered while testing the go sdk.
Just saw this that might be interesting for automatically generating the OpenApi document from the code: https://github.com/juhaku/utoipa
I'm reluctant now to make further changes to the admin api given how much work it is to fix all the generated sdk frameworks, but if we have something like this maybe it can be made easier.
I have a new issue with the SDK: https://github.com/OpenAPITools/openapi-generator/issues/17208
I did not test the golang SDK as extensively as I would like, but it's way better now (see example/golang/main.go for example).
Concerning the generation of the OpenAPI spec, my opinion on the subject is that there is no shortcut: we will have to describe the API in a formalized language anyways, we will have to document it and publish it anyways, and we will have to manually fix / find workaround for impedance mismatches between languages (like this golang one or this python one). I think it will simply move the work of specifying the API from me to Alex in the end basically, which could be (or not be) a desired outcome.
More globally, there is in general 2 approaches to OpenAPI: a code-centric and a protocol-centric. In the code centric, what matters is the code and the REST API spec is a byproduct of it you can generate. In the protocol-centric, you define the API and then implement your code following its specification, often by generating the server as well as the client.
Personally I don't like code generation and I prefer protocol-centric approaches: we define the API specification and then we implement it by using as few code generation as possible. By following this path, we acknowledge that the API, the contract, the interface is more important than the code, the algorithm behind, and that it will survive it.
But to be 100% fair, today we still have a code-centric approach as we did not discuss the API design before its implementation.
In this vein, I really like the work / the idea of Amazon on the subject, with Smithy and the idea they present in their talks. But currently, Smithy was a too high step for me, that's why I chose OpenAPI with which I'm more confortable.
But I must admit that my time is also limited, and if someone has the time and the will to maintain better Garage SDKs than me, that are shipped faster, I am very open to a maintainer transition, and it could be the opportunity to change how we handle the SDK generation.
WIP: Implement APIv1to Implement APIv1Implement APIv1to OpenAPI specification of APIv1OpenAPI specification of APIv1to OpenAPI specification of admin APIv1I have merged all my PRs in the garage-sdk organization. I let you synchronize this PR with main, merge it as you like (feel free to rebase/squash the PR). Feel free to push modifications directly on the branch if required.
If we find issues in the SDK later, I will handle them as bugs and fix them as they arrive.