Tips for (XR) API design

[negz]

What's Missing?

One challenge folks getting started with Crossplane have is how to design their custom APIs - i.e. how to design XR OpenAPI schemas. It's hard to go from nothing to a serviceable API that can evolve over time without breaking changes.

I think the Crossplane maintainers will have some useful tips for this. A lot of our job is designing new APIs for Crossplane, and we've certainly made and learned mistakes with Crossplane's APIs. Kubernetes API conventions capture a lot of this and we could draw out some of the more important things called out in that document. I'd also include things like:

• If you're introducing a new object (e.g. spec.databaseConfiguration), could it be implemented a few different ways in future? If so, consider using a type differentiator field (e.g. spec.databaseConfigurationType) and nesting each type's configuration in its own object.
• If you introduce an array of objects, always require some field that uniquely identifies each object (e.g. name).
• Always look at your API through the lens of "how far could I evolve this API by only adding new optional fields?"