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?"

[negz]

I think this would probably include #478.

[negz]

Another little thing: don't make status fields required.

[jbw976]

This K8s API doc on "Changing the API" is probably also helpful here: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md

This document is oriented at developers who want to change existing APIs