omallassi / apis-catalog Goto Github PK

[

⚠️ All of this is, at this stage ideas, POC...tested in real life.

In all companies that expose APIs (so in fact all companies in 2020), there is a need to ensure a proper level of quality and consistency of these APIs, as they reflect your product, its quality and its capabilities.

This is then not uncommon then to talk about API Governance. Usually, when you talk about governance, you get this reaction: "Outch! Governance! That's from another age". Well, I do think governance is still needed even if I do believe this is complex balance and it can quickly fall into a trap of becoming a bottleneck for the rest of the organisation.

Talking about Governance, you can think about (at least) :

• Design time Governance where we usually try to manage questions like : What are my APIs? how many versions of my specifications do I have? Are my APIs syntaxically correct (ie. how many zally ignore do I have...) ? Are my APIs semantically correct (hum, this one will generate a lot more discussions)? Are security and compliance policies followed? Is this evolution backward compatible (or not)? How frequent is an evolution on my APIs?

• Runtime Governance where we usually try to manage questions like : Where are my APIs deployed (on which environments, which gateways...)? how many versions are deployed? is this API still used (or not) ?

A lot of great solutions exists in these spaces and the goal here is not to replace any of them.

The goals are

• to ease keeping track of your endpoints and APIs (it currently supports OpenAPI, AsyncAPI etc. but could evolve) : from inception to production and end of life
• to help having an overview of the specs accross all possible catalogs of your organisation, the volumes of endpoints,
• to help you understanding your domains, how they spread per layers and systems etc.
• to help you monitoring the efficiency of your governance process (whatever it is)

With the following principles in mind:

• reuse and integrate with simple, massively used open source frameworks (like git, perforce, jenkins...)
• reuse and integrate with existing specification formats (e.g. OpenAPI, AsyncAPI...)
• Help organising your API specifications : in domains, with owners, in environments etc...
• give as much freedom as possible with respect to "reviews or validation workflows". The best freedom being to not provide anything, any kind of workflow on this topic.
• do not be on the critical path of anything related to CI / CD pipeline, just keep track of things, and stay optional
• accept to fail & have fun with Rust (ok, langage has nothing to do here but I tend to like Rust and would like to continue learning it)

This picture tries to depict a possible state :

NOTE: from the above schema, the box apis-catalog is the current github repository whereas the box apis-catalog-web is the this repository.

Refer to this page to get a list of available statistics and their definitions.

There are two clients that can be used

• a CLI.
• a Web UI that provides part of the CLIcapabilities in terms of management but provides additional reports and statistics.

Please refer to this page

available in the wiki.