openshift-online / ocm-api-model Goto Github PK
View Code? Open in Web Editor NEWLicense: Apache License 2.0
License: Apache License 2.0
Historically, both in openapi and in backend Go code, CS & AMS used same types to represent:
POST
body when creating resource.POST
response. Normally same as:GET
vs. optional. This depends on lifecycle stage and also on cluster type in complicated ways... (the best case is omitting whole sub-structs e.g. "aws": {...}
)PATCH
— all are optional here (and Go type marks all pointers to detect omission vs. zero value after de-serialization); some are read-only and can't be patched (but Go type includes them so they can be de-serialized so validator can return error if you sent them)."kind": "FooLink"
fields are not present at all but only link to other resource with kind
, id
, and href
. In CS at least, these still reuse the api.Foo
Go structs, forcing all but these 3 fields to be optional pointers.?fetchFoo=true
params like that, but they are small minority.)required
in openapiAnd for consumers of the API, nearly all fields being optional conveys zero information.
This is a hard problem to attack!
I don't know if it's realistic to move the needle on actual type level, but it's systematically lacking documentation UI would be glad to get even in the form of comments, for a start 🙏
At least in metamodel where we make up the rules, we can add formalized notations for all this.
Defining unrelated models e.g. PostCluster
vs. PatchCluster
here would be a mistake IMHO. It's valuable to know it's same resource with same fields, they just behave differently under different verbs.
1. POST body: in resource
definitions, we have in
option. But I don't think this says anything about POST vs. PATCH bodies, and it doesn't exist for class
files... I think POST needs 3 distinct behaviors:
@Add(required)
— it's an error if you omit this field.@Add(optional)
— default if not specified? probably doesn't need syntax.@Add(never)
— it's an error if you send this field (e.g. metrics
).Do we need support for separate APIs taking different subsets of same type? iirc AMS has 2 endpoints for creating cluster vs. register offline cluster, but that's rare. Let's ignore for now but keep in mind future possibility of more "verbs".
2. can ignore, assume POST response == GET response.
3. GET: in resource
definitions, we have out
option. But I think GET needs 3 distinct behaviors.
@Get(required)
— it's an error if you omit this.@Get(optional)
— default if not specified? probably doesn't need syntax.@Get(never)
— it's an error if you send it (e.g. metrics
).Is there value in separating @Get
vs @List
annotations? Not initially.
4. PATCH: nothing is required, so I think needs 2 behaviors:
@Patch(optional)
@Patch(never)
— it's an error if you send it (e.g. metrics
).I'm not sure what should be default. Frequently you can PATCH a field iff you can POST it, but sometimes it's only day-1 or only day-2 (and tends to get relaxed over time).
5. We already have link
notation e.g. link Region CloudRegion
.
The syntaxes proposed above are "strawman" suggestions. I'm not even sure they should use annotation @
style.
out of scope here, just mentioning to show this could be used in various ways...
openapi: append this data to description
openapi: emit custom x-...
fields
openapi: emit separate types for different scenarios?? [disruptive to existing consumers, including AMS code generation]
backend: auto-generate validations of required/never fields under various verbs.
Either as code, or as custom Go struct tags that can be introspected at runtime.
I notice none of the method List {
blocks contain an out Kind String
parameter.
And indeed the generated openapi documents kind
for individual objects corresponding to method Get
eg. /api/clusters_mgmt/v1/clusters/{cluster_id}
but not for collection lists e.g. /api/clusters_mgmt/v1/clusters
@nimrodshn @jhernand I can send a PR to add those, will that be enough?
I see generated server code has special logic to return correct Kind, including link vs full object.
Will it automatically also return kind for lists?
Following SDB-2391 the MT-SRE team would like /api/accounts_mgmt/v1/quota_rules
to be available in the api model and consequently ocm-sdk-go
.
This ticket is just for MT-SRE tracking since that endpoint is still very new.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.