OpenAPI spec for admin API #379
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
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference: Deuxfleurs/garage#379
Loading…
Reference in a new issue
No description provided.
Delete branch "ecosystem/openapi"
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?
last_seen_sec_agocan be null, cause an error with python currentlyCheck:
93ad9f09a5tobbe38a9b30WIP: OpenAPI specto WIP: OpenAPI spec for admin API008119e1batoba679223107b257b21c2to72a0f90070WIP: OpenAPI spec for admin APIto OpenAPI spec for admin APILGTM, awesome work.
Two questions:
Couldn't we rather have them in the website repository,
garagehq.deuxfleurs.fr?We can put the Redocly dependencies (fonts, css, js, etc.) in GarageHQ but we will loose a way to visualize and check the spec from Garage's repository. I have no strong opinion on that, feel free to do what you prefer here, we might find a tool that would be easy to install and that could be used to validate the file, without having to rely on this html+css+js viewer.
Concerning the API specification part, if we consider the API is designed to connect Garage to other software, we will have to maintain more or less stable interfaces over time, so I think clearly defining it is important. I would also prefer that we define the API first and then implement the code in a second time.
In practise, I just noticed that my specification is already outdated. I think that we can live with it as long as the change is backward compatible.
I also plan to use the Smithy IDL (Interface Definition Language) instead of OpenAPI which seems to be both less verbose, more versatile and more precise. If we want to reduce the complexity of maintaining both a specification and some codes, we could use some code generation tools (smithy can output an openapi spec than can be used to generate rust server code, or more directly, amazon has smithy-rs that can directly generate rust client+server code).
Directly writing our own Rust macros is also an option: Smithy can output machine readable JSON that could be used to generate our code for the JSON structures (aka the models in Smithy, schema in OpenAPI, and the serde strutures in our code) and the services endpoints, it would probably result in a more efficient and better tailored solution. I don't know if you want to follow this path, personally I don't find it necessary as long as we are able to stabilize APIs, but writing macros from the Smithy JSON output would be an interesting challenge ;-)
More generally, I think that my future work on Garage will be dedicated to create an ecosystem around it: I have the feeling that we have accomplished a lot and now, we must "unlock" this work to others by making it accessible/usable.
I would like to see Garage becoming an alternative to both Netlify/Vercel and Firebase/Firestore services. Given this goal, specifying clear interfaces on the K2V and administration API and having easy to use SDK for popular languages seems to be important. Being busy, I can't commit on being always available, but yes I think I can be listed as the maintainer of the Garage SDKs for now.
Edit: this talk might be of interest: https://www.youtube.com/watch?v=3GpZzu4guTE