lbroudoux
commented
2 years ago Repository Organization in Microcks stands for the way you classify the API & Services of the repository of a Microcks instance. But the first thing to consider may be : how many Microcks instance may you have in your organization?
On Microcks instances organization
From field feedback, we’ve seen different approaches following those patterns :
- Global and central repository : 1 Microcks instance for holding all the APIs of the organization - whatever the status (draft, developed, deployed), whatever the visibility (public, internal, private)
- Distributed repositories [+ aggregation] : N Microcks instances each holding the APIs of a functional domain (or a BU) whatever the status and the visibility. In addition, some organizations also deploy a unique central Microcks instance that consolidates APIs with specific status or visibility (ie. the stabilized public ones)
- Ephemeral repositories that are Microcks instances that are just deployed during a CI/CD pipeline execution or a dedicated performance campaign. In those cases, Microcks is especially used to break dependencies and simulate them while some other tests (integration, user acceptance, performance) are running on the application under-test.
The « one Microcks per developer on her laptop » is also a pattern we saw but that is much more transitional before actually deploying distributed or central instances.
Microcks features
Microcks has specific features for managing these different patterns :
labelscan be set to the different APIs of an instance in order to let users map repository structure on their own classifications needs. This labels can be used to setdomain,status,type,pattern,team,applicationor whatever. See Organizing repository | Microcks.io- RBAC segmentation can be applied on a
masterlabel in order to have fine-grained permissions on the different APIs of a big repository. See RBAC Segmentation | Microcks.io - Repository import and export can be used to load / transfer / aggregate content from different sources into an instance repository. Some people are using this to automate the promotion of APIs from distributed to central instances. See Repository Snapshots | Microcks.io
As you see, labels are a very important point in Microcks repository organization - they have the same role than in Kubernetes. But how can you set labels to an API? There are different ways of doing this:
- Using specification extensions ! You can set
labelsinto your OpenAPI or AsyncAPI specs. See OpenAPI usage for Microcks | Microcks.io for example, - Using Microcks API : you can associate labels to API using the Microcks API. See Microcks API | Microcks.io
- Using the GUI : You can set labels after an API Import from the Web UI,
- Using a specific
APIMetadataartifact. When it’s not possible / desirable to use spec extensions, you can use this-specific artifact - aside your main spec in your Git repository for example and import it into Microcks. See Microcks API | Microcks.io
Git repository organization
The last topic I foresee about repository organization in the Microcks context is the question of the Git repository holding the API artifacts organization.
Form the field, we’ve seen many different things - depending on the human organization and its maturity regarding domain driven design most of the time. However, there’s this particular organization that is described below and that I tend to promote:
https://git.acme.com/<domain_1>
/apis | products
/sub-domain
myapi-openapi-v1.0.yaml
myapi-apimetadata-v1.0.yaml
myapi-collection-tck-v1.0.json
myevent-asyncapi-v1.0.yaml
/app_1 | microservice_1
/src/main
/java
/resources
myapi-openapi-v1.0.yaml
/tests
myapi-collection-dataset-v1.0.json
/staging
/app_1 | microservice_1
myapi-collection-ua-dataset-v1.0.json
myapi-collection-perf-dataset-v1.0.jsonSome explanations:
-
The top level here is a Git organization corresponding to the
domain- or the organisation unit level or the urbanisation unit level you have decided to set the IS break-ability level upon), -
Within this top level lies a dedicated repository for all the things related to the description of business capabilities this domain brings to the organization. That’s where live the
productsof the domain and so theAPI definitions. They may be organized by sub-domains for large ones and you may find OpenAPI / AsyncAPI specifications as well as Microcks APIMetadata defining the ownership or some behavioral refinements. You’d probably add to this some Postman Collection holding documentation or tests playing the role of TCK (Test Certification Kit) for future implementations of APIs. -
You’ll also find within this
domain, many repositories related toapplications | microservices | functions | implementations componentsrelated to this domain. This is where the code lives and these components will need resources references to the specification they’re implementing (maybe for code skeleton generation purposes). I think its also a best practice to have these components managing their Postman Collection for specifying additional examples dataset.- The nice thing of defining this here being that there’s great chance for this dataset to be in-sync with other implementation specific dataset (ex: a SQL script loading a database)
- The bad thing of defining this here being that it may contain edge cases that may have been detected at implementation time and that may not have been pushed upstream at the product definition level. So there’s a risk of API products spec and TCK drifting from the reality…
-
Finally there’s usually this need to manage additional datasets for specific simulation or testing needs during the
stagingprocess. Postman Collection are perfectly suited for that purpose. Hence we may find specific collection for specific app or microservices that may be used within ephemeral Microcks instances as explained above.
I would like to create an API blueprint for how repositories should be organized, publish it as a formal blueprint at APIs.How, and use to tell a story about this level of organization within API operations.