Since GamingAPI are open source, I want to create some consistency and set the level of expectation that one can expect from the project.
So what are API governance? Well, there are different interpretations of it, Janet points to 9 different things to focus on, Kin points to 5, but what they both points towards one thing. I like to think about this as if your API's was a government, how does the government govern?
What I want to focus on at the moment are what Kin refers to as discovery, consistency, and delivery.
I feel like it's important to set a level of consistency when designing the APIs. This makes it easier for others to consume them and even contribute to them. Currently, I have all of the AsyncAPI documents in a GitHub repository. It is also here that most of these consistencies must be enforced, you can read more about it in Enforcing consistency guidelines.
I do have a few requirements regarding the consistency guidelines though.
- It MUST be executable locally on the developer's machine, so you don't have to wait to check whether your changes will go through the CI.
- It MUST be a required check for making ANY changes to the AsyncAPI documents. This means that we should be confident that if all automated checks pass there should be no problems in merging the change.
On to the specific design guidelines, few of them are gonna be borrowed directly from Zalando's API guidelines:
- MUST contain API meta information .
- MUST treat events as part of the service interface ).
- MUST use semantic versioning  (read more about the versioning strategy here).
- MUST follow API first principle .
- MUST write APIs using U.S. English .
- MUST property names must be snake_case (and never camel case) .
Furthermore, the following is added to extend the above:
- MUST use the same schema format partly spired by 196 (because both REST and NATS are used, sharing the message schema payload between the two specifications is a must).
- MUST name date/time properties with
_atsuffix inspired by 235.
- MUST declare enum values using
UPPER_SNAKE_CASEstring inspired by 240.
- SHOULD avoid
additionalPropertiesunless used as a map partly inspired by 210 (each object should be as constrained as possible and
additionalPropertiesshould not be used unless used to define a map.).
- MUST never break compatibility (read more about the versioning strategy here).
- MUST include semantic versioning in channels (each channel and path must use resource versioning. Read more about the versioning strategy here).
- MUST treat version 0 as work in progress (when getting started, changes happen rapidly, and to accommodate that, any time version 0 is used either in the documents or in a channel, it MUST be treated as work in progress and can potentially contain breaking changes without notice).
- MUST use references where at all possible (to leverage reusability, references MUST be used where at all possible).
I want to set some requirements for the delivery of the APIs and what consumers can expect from them.
- MUST monitor all GamingAPI services (If there exist services within the GamingAPI network they MUST be monitored).
- MUST make pre-built clients easily accessible for each public consumer (if it is expected others (outside of GamingAPI are a consumer or producers of events, i.e. the AsyncAPI document is targeting them) pre-built binaries MUST be made available. This will be through code generation from the specification).
- MUST always use the newest specification version (each time a new specification version is released, the underlying documents must be kept up to date).
I think it is important to set a level of discoverability for the APIs, it's not enough that they are there, people also need a way to discover them.
- MUST make all public API's available on gamingapi.org (not only simple API documentation, but also more complex event discovery and relations).
- MUST provide API specification using AsyncAPI inspired by #101.
- MUST make the governance guidelines available on gamingapi.org to make them easily discoverable.
There are a lot of different perspectives that I have not taken into account, some I do plan to include at a later time:
- As I have no experience with deprecation in production, I have left that out for now until I encounter it and can take a stance on it.
- As mentioned with the NATS setup, I still have to figure out how to handle access control. And the solution for that needs to be added as part of the governance guidelines (I think).
Photo by Aditya Joshi on Unsplash