Skip to content

registry compute

Jump to bottom
Scott Ganyo edited this page Apr 27, 2023 · 9 revisions

Registry compute command offers a variety of operations that can be run on the API information stored in the registry. Some examples include computing lint results (which we call the conformance report), computing scores, etc.

Important note: registry compute conformance requires local installation of any linters used in the style guide:

More details in in subsequent headings.

registry compute complexity

Compute complexity metrics of API specs

registry compute conformance

Compute lint results for API specs

  • API style guides can be stored in the registry in a structured format described in Schema for API Style Guides.
  • With registry compute conformance, the registry tool checks conformance of an API spec with the appropriate API style guides. registry compute conformance uses a plugin interface that by convention, will use a plugin named registry-lint-api-linter to run the linter described in the style guide.
  • Conformance results are represented with ConformanceReport messages described in conformance_report.proto. These are stored in the registry as artifacts attached to the associated API specs.
  • Conformance is summarized with scores that are computed based on the conformance reports. Score Definitions are stored at the top level of a project and are used by registry compute score to compute Score values associated with specs. Scores can be grouped together for display in ScoreCards that are computed automatically using ScoreCard Definitions.

For more discussion, watch Incenting Better APIs with API Scoreboards - Shruti Parab, Google from the 2022 API Specifications Conference.

registry compute lint

Soon to be deprecated, please check compute conformance command.
Compute lint results for API specs

registry compute lintstats

Soon to be deprecated, please check compute score command.
Compute summaries of linter runs

registry compute score

Compute scores for the entities stored in the registry.

Computing a guided score

  • This command computes a score for the supplied resources and creates a Score artifact under that resource. Scores are calculated based on the ScoreDefinition artifacts which are expected to be present as the project level artifact in the registry.
  • You can get a list of existing ScoreDefinition artifacts using the following command:
registry get projects/$PROJECT/locations/global/artifacts/- --filter="mime_type.contains('ScoreDefinition')"

Get the explanation of the definition by referring to the ScoreDefinition proto.

  • Here is an example of how to define a ScoreDefinition yaml. You can upload it to the registry using registry apply -f apihub-lint-errors.yaml --parent=projects/$PROJECT/locations/global.
  • An example usage of the command is registry compute score projects/demo/locations/global/apis/petstore/versions/v1/specs/openapi.yaml. The tool will pull all the suitable score definitions from the registry and compute a corresponding score which will be stored as an artifact under the supplied spec. A collection of resources can also be passed to this command and it will calculate the score for all the supplied resources.

Attaching a Score artifact

  • The guided score path is a full end-to-end user journey where you get to define your own score definitions and how the score is calculated. But there is also a lightweight way to attach scores. You can directly attach a self computed score artifact to an entity (let's take spec as an example here).
  • Create a file named score.yaml and generated the yaml by referring to the score proto. Once you have the yaml file, simply apply it using registry apply -f score.yaml --parent=projects/demo/locations/global/apis/petstore/versions/v1/specsopenapi.yaml.
  • Refer to registry apply for more details on how to construct the yaml.

registry compute scorecard

Compute score cards for APIs and API specs. A score card is a group of scores which can be viewed together.

Computing a guided score card

  • This command computes a score card for the supplied resources and creates a ScoreCard artifact under that resource. ScoreCards are calculated based on the ScoreCardDefinition artifacts which are expected to be present as the project level artifact in the registry.
  • You can get a list of existing ScoreCardDefinition artifacts using the following command:
registry get projects/$PROJECT/locations/global/artifacts/- --filter="mime_type.contains('ScoreCardDefinition')"

Get the explanation of the definition by referring to the ScoreCardDefinition proto.

  • Here is an example of how to define a ScoreCardDefinition yaml. You can upload it to the registry using registry apply -f apihub-lint-summary.yaml --parent=projects/$PROJECT/locations/global.
  • An example usage of the command is registry compute scorecard projects/demo/locations/global/apis/petstore/versions/v1/specs/openapi.yaml. The tool will pull all the suitable scoreCard definitions from the registry and compute a corresponding score card which will be stored as an artifact under the supplied spec. A collection of resources can also be passed to this command and it will calculate the score card for all the supplied resources.

Attaching a ScoreCard artifact

  • The guided score card path is a full end-to-end user journey where you get to define your own score card definitions and how the score card is calculated. But there is also a lightweight way to attach score cards. You can directly attach a self computed score card artifact to an entity (let's take spec as an example here).
  • Create a file named score_card.yaml and generated the yaml by referring to the ScoreCard proto. Once you have the yaml file, simply apply it using registry apply -f score_card.yaml --parent=projects/demo/locations/global/apis/petstore/versions/v1/specsopenapi.yaml.
  • Refer to registry apply for more details on how to construct the yaml.

registry compute vocabulary

Compute vocabularies of API specs

Clone this wiki locally