Maturity in API governance at Kyriba
By Oleksii Pylypenko
Principal Architect, Connectivity
When we at Kyriba embarked on implementing API governance principles, we began with Code-First contracts, which presented many complexities in managing our APIs. These challenges often resulted in delays in software delivery and contract processes. However, we are thrilled to share that we have since made significant progress and achieved a good level of maturity in our API governance. This improvement has enabled us to streamline our operations and enhance overall efficiency, ensuring smoother software delivery and contract management.
High-level vision
What was good from the start is that our CTPO was inspired by an API mandate from Jeff Bezos, postulating every team should take API design seriously to produce contracts of great quality, as if every API is an externally published contract.
Additionally, we decided to move towards API-First design.
Here are a few key points from early mail discussions:
- The internals of your implementation are a black box to the rest of the world.
- It applies to both new things (a brand new service) or refactoring older things (decoupling of Core or Payments, for instance).
- API contracts have to be designed to be semantically meaningful - the outside user is unaware how it's done inside, but he/she needs to be able to understand quickly on how to use our services by just reading the service contracts.
- And they have to be designed to last. You don't change the service contracts on the thousands, millions of users who may decide to use them.
- It's very much recommended to approach design API-First (what your service will do for the users) before you even start implementation.
- Above applies to any service of any size from micro (even nano if you like) to macro to mega.
This gave solid confidence that we are covered from upper-management levels while changing the culture of the whole company.
Architectural shift
Kyriba's externally visible APIs are growing and outnumbering 100 million calls recently. But additionally Kyriba is quickly moving towards a more and more distributed microservice approach. This means that what was designed around databases needs to be mentally shifted towards internal and external API contract designs.
In this approach, Open API definitions become key points where “early technical design” happens. To build an API we would like to capture different opinions on a definition from product, technical and governance sides and collaborate to build the API properly and quickly.
Our database captures a high number of entities and we expect many of them to appear as APIs, thus we started to settle ground for principles of API design and guidelines. This is required to achieve uniformity of APIs and have some common rules of the game that are possible to reference in discussions.
API design principles
Based on certain research on different known API guidelines we established the following principles around which our APIs are organized.
This is mainly required for establishing a proper initial mindset for people starting the API design as well as serves as a meta-logical foundation for REST guidelines.
REST guidelines
Currently, our main focus is REST Open API definitions. While establishing design rules for these contracts we gathered experience from our initial phase of “Code-First” governance, while enriching it with a multitude of existing REST API guidelines:
Later we plan to add Async API guidelines to support event-driven communication contracts.
As a basis for building REST guidelines, we were inspired by RFC standard document structure, with MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL verbs explained in RFC2119.
To sum up, our Open API design guidelines is a set of common rules, explained in one document and covering various aspects of API design.
Here is an example:
Every rule is possible to reference via URL and may be used to prove that or another point in discussions during the review.
Centralized contract repository
Apart from implementing API guidelines, the central concept of API governance was to establish a centralized Git repository that stores Open API contracts. This repository holds a significant role in managing APIs effectively.
This has various benefits:
Contracts are easily discoverable.
By leveraging pull requests, we get to a common understanding of proper design.
We are protecting the quality of contracts by automated lint rules.
Generate client/server artifacts usable in projects directly.
Release artifacts and contracts and properly maintain versioning.
Build pipeline automation is written in Java and smart enough to build only changed contracts in Git difference, as well as take into account various other conditions.
With time we involved early adopters and fixed several things that emerged during “beta” use. After early adoption we announced the “API center” project, what we call git repository, build automation and static accompanying website to the whole company and incentivize through several other ways people use it.
Internal portal
Automation upon each master build updates a static website that contains tutorials, REST guidelines, and API definitions. Here people may discover recent versions of contracts as well as learn about processes as well as master design guidelines.
Lifecycle management
Each contract starts as a new Open API definition in the API center Git repository on a local computer. At this stage, it is possible to leverage automation to build artifacts and use them in both client and server, as well as leverage linting. This serves the purpose of quick validation, making development cycles quicker.
Typically contracts are started as “v0” major versions. Which means this is a draft contract. We define this stage as a contract that is usable for demoing/piloting purposes including the production environment, but not suitable for general availability. It must not be used for such production traffic.
When we bump a major version of a contract we are obliged to create another Open API definition for it in the git repository and basically, this becomes an independently maintainable contract. Automation tracks breaking changes that appear in pull requests and flags them. Each such case requires adequate investigation if it should result in a major version bump of a contract.
Automation works the way that if we merge a contract to master, then it is released with the version specified in Open API definition. Our automation blocks pull requests from being merged if a contract is modified, but the version of it is not bumped.
Contract review
When we, the API team, are reviewing pull requests we try to help developers to build good quality contracts. In every review, we are incentivizing teams to follow company guidelines, as well as build sane naming and organization of contracts, but we may tolerate several things if a contract is drafted.
Based on our current experience internal contracts are less clear in the sense of context this contract is used for and may require some technical specifics that this exact communication requires, so we try to achieve some compromise in API design.
External contracts are typically reviewed a lot more in a strict manner, requiring the contract to adhere to the full set of REST guidelines, as well as fitting the overall Kyriba API landscape.
Roles and responsibilities
In the review process of API contract definition, different parties might have different interests:
Product managers and business analysts would like to satisfy consumers of APIs, getting value out of selling APIs to them.
The developer team is interested in having documented, published, and easy-to-consume specifications.
The consumer side would like to easily start development with the provided specifications, having as many as possible things defined inside of specifications to reduce communication turn-around between teams.
API product management would like API to fit in an ecosystem of APIs, adhering to common rules of building them and providing a holistic perception of API products to customers.
API architects would like APIs to adhere to certain rules of architecture, introspecting the state of all APIs in company, as well as have control over newly created APIs.
API team stays in guard of best practices of API construction and adhering to REST guidelines on the level of code.
Our experience is that participating in collaborative API design makes a lot of sense and is easily achievable with Git pull requests.
Conclusion
In conclusion, the API center project stands as another crucial component contributing to Kyriba's ongoing success. Moving forward, our focus remains on expanding both the quantity and quality of APIs, while also prioritizing agility. By doing so, we aim to further enhance our services and solidify Kyriba's position as a leading force in the industry. We are excited about the opportunities ahead and are committed to continuous improvement and innovation.