openapi.yaml

openapi: "3.1.0"
info:
  version: "0.1.0"
  title: Grafana k6 Extension Registry Service
  summary: Query the Grafana k6 Extension Registry database.
  description: |
    The **Grafana k6 Extension Registry Service** enables read-only access to the Grafana k6 Extension Registry database.

    The Grafana k6 Extension Registry database contains **up-to-date information about registered extensions**. The basic data of the extensions (e.g. go module path, JavaScript import path, description) are registered manually, the other data (e.g. available versions, number of stars) are retrieved automatically via the **repository manager API** (GitHub, GitLab, etc.).

    Detailed information about response schemas can be found in the [schema documentation](https://registry.k6.io/schema). Schemas are defined in [registry.schema.json](https://registry.k6.io/registry.schema.json)

    The source code of extensions is automatically **statically analyzed**. The result of the analysis is the **compliance level** of the best practices of Grafana k6 extensions (0-100%). Based on the compliance level, a **compliance grade** is also calculated (A-F). Based on the compliance grade, an SVG **compliance badge** is created for each extension. Example badge:

    ![xk6-sql](https://registry.k6.io/module/github.com/grafana/xk6-sql/badge.svg)

    The k6 Extension **Catalog** is an **alternative representation** of the k6 Extension **Registry**. Most queries have an alternative counterpart that returns a catalog instead of a registry.

    You can [try the k6 Extension Registry Service](https://registry.k6.io/ui)!

    Information about modifying the registry (register new extensions, modify or delete existing registrations) can be found in the [grafana/k6-extension-registry](https://github.com/grafana/k6-extension-registry) GitHub repository.
  termsOfService: https://grafana.com/legal/terms/
  license:
    name: AGPL-3.0-only
    url: https://www.gnu.org/licenses/agpl-3.0.html
externalDocs:
  description: Find out more about Grafana k6 extensions
  url: https://grafana.com/docs/k6/latest/extensions/
servers:
  - url: https://registry.k6.io
tags:
  - name: global
    description: Access to the entire registry
  - name: module
    description: Query a specific extension
  - name: catalog
    description: Extension catalog queries
  - name: subset
    description: Query subsets of the registry
  - name: metrics
    description: Registry metrics queries
paths:
  /registry.json:
    get:
      tags:
        - global
      summary: Entire registry
      description: Download the entire registry as a single JSON file
      operationId: entireRegistry
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
  /catalog.json:
    get:
      tags:
        - catalog
      summary: Entire catalog
      description: Download the entire catalog as a single JSON file
      operationId: entireCatalog
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/catalog"
  /metrics.json:
    get:
      tags:
        - metrics
      summary: Registry metrics
      description: Download the registry metrics as a single JSON file
      operationId: getMetrics
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/metrics"
  /metrics.txt:
    get:
      tags:
        - metrics
      summary: Registry metrics in Prometheus text format.
      description: Download the registry metrics as a single TXT file in Prometheus text format
      operationId: getMetricsPrometheus
      responses:
        "200":
          description: successful operation
          content:
            text/plain:
              schema:
                type: string
              examples:
                simple:
                  summary: Simple example
                  value: |
                    # HELP registry_tier_official_count Number of extensions in the 'official' tier.
                    # TYPE registry_tier_official_count counter
                    registry_tier_official_count 14 1733941259568
                    # HELP registry_type_javascript_count Number of JavaScript extension.
                    # TYPE registry_type_javascript_count counter
                    registry_type_javascript_count 56 1733941259568
                    # HELP registry_type_output_count Number of Output extension.
                    # TYPE registry_type_output_count counter
                    registry_type_output_count 16 1733941259568
                    # HELP registry_grade_d_count Number of D-grade extensions.
                    # TYPE registry_grade_d_count counter
                    registry_grade_d_count 2 1733941259568
                    # HELP registry_issue_examples_count Number of extensions without examples directory.
                    # TYPE registry_issue_examples_count counter
                    registry_issue_examples_count 14 1733941259568
                    # HELP registry_tier_community_count Number of extension in the community' tier.
                    # TYPE registry_tier_community_count counter
                    registry_tier_community_count 57 1733941259568
                    # HELP registry_grade_a_count Number of A-grade extensions.
                    # TYPE registry_grade_a_count counter
                    registry_grade_a_count 22 1733941259568
                    # HELP registry_grade_c_count Number of C-grade extensions.
                    # TYPE registry_grade_c_count counter
                    registry_grade_c_count 44 1733941259568
                    # HELP registry_product_cloud_count Number of extensions available in Grafana Cloud k6.
                    # TYPE registry_product_cloud_count counter
                    registry_product_cloud_count 4 1733941259568
                    # HELP registry_category_observability_count Number of extensions in the 'observability' category.
                    # TYPE registry_category_observability_count counter
                    registry_category_observability_count 12 1733941259568
                    # HELP registry_extension_count The total number of extensions.
                    # TYPE registry_extension_count counter
                    registry_extension_count 71 1733941259568
                    # HELP registry_issue_smoke_count Number of extensions without smoke test script.
                    # TYPE registry_issue_smoke_count counter
                    registry_issue_smoke_count 49 1733941259568
                    # HELP registry_category_misc_count Number of extensions in the 'misc' category.
                    # TYPE registry_category_misc_count counter
                    registry_category_misc_count 14 1733941259568
                    # HELP registry_tier_unofficial_count Number of unofficial extensions.
                    # TYPE registry_tier_unofficial_count counter
                    registry_tier_unofficial_count 11 1733941259568
                    # HELP registry_category_kubernetes_count Number of extensions in the 'kubernetes' category.
                    # TYPE registry_category_kubernetes_count counter
                    registry_category_kubernetes_count 2 1733941259568
                    # HELP registry_category_reporting_count Number of extensions in the 'reporting' category.
                    # TYPE registry_category_reporting_count counter
                    registry_category_reporting_count 13 1733941259568
                    # HELP registry_issue_build_count Number of extensions not buildable with the latest k6 version.
                    # TYPE registry_issue_build_count counter
                    registry_issue_build_count 3 1733941259568
                    # HELP registry_category_browser_count Number of extensions in the 'browser' category.
                    # TYPE registry_category_browser_count counter
                    registry_category_browser_count 1 1733941259568
                    # HELP registry_category_data_count Number of extensions in the 'data' category.
                    # TYPE registry_category_data_count counter
                    registry_category_data_count 24 1733941259568
                    # HELP registry_grade_b_count Number of B-grade extensions.
                    # TYPE registry_grade_b_count counter
                    registry_grade_b_count 2 1733941259568
                    # HELP registry_grade_e_count Number of E-grade extensions.
                    # TYPE registry_grade_e_count counter
                    registry_grade_e_count 1 1733941259568
                    # HELP registry_product_oss_count Number of extensions available in Grafana k6.
                    # TYPE registry_product_oss_count counter
                    registry_product_oss_count 70 1733941259568
                    # HELP registry_product_synthetic_count Number of extensions available in Synthetic Monitoring.
                    # TYPE registry_product_synthetic_count counter
                    registry_product_synthetic_count 2 1733941259568
                    # HELP registry_cgo_count Number of extensions requiring cgo.
                    # TYPE registry_cgo_count counter
                    registry_cgo_count 1 1733941259568
                    # HELP registry_issue_replace_count Number of extensions with replace directive in go.mod.
                    # TYPE registry_issue_replace_count counter
                    registry_issue_replace_count 2 1733941259568
                    # HELP registry_issue_types_count Number of extensions without API declaration file.
                    # TYPE registry_issue_types_count counter
                    registry_issue_types_count 42 1733941259568
                    # HELP registry_category_authentication_count Number of extensions in the 'authentication' category.
                    # TYPE registry_category_authentication_count counter
                    registry_category_authentication_count 2 1733941259568
                    # HELP registry_category_messaging_count Number of extensions in the 'messaging' category.
                    # TYPE registry_category_messaging_count counter
                    registry_category_messaging_count 11 1733941259568
                    # HELP registry_category_protocol_count Number of extensions in the 'protocol' category.
                    # TYPE registry_category_protocol_count counter
                    registry_category_protocol_count 10 1733941259568
  /module/{module}/extension.json:
    get:
      tags:
        - module
      summary: Query an extension
      description: Query the data of a specific extension as a single JSON file
      operationId: getExtension
      parameters:
        - $ref: "#/components/parameters/module"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/extension"
        "404":
          description: module not found
  /module/{module}/badge.svg:
    get:
      tags:
        - module
      summary: Download a badge
      description: |
        Download an extension's badge as an SVG image

        Example:

        ![xk6-sql](https://registry.k6.io/module/github.com/grafana/xk6-sql/badge.svg)
      operationId: getBadge
      parameters:
        - $ref: "#/components/parameters/module"
      produces:
        - image/svg+xml
      responses:
        "200":
          description: successful operation
        "404":
          description: module not found
  /module/{module}/grade.svg:
    get:
      tags:
        - module
      summary: Download a grade badge
      description: |
        Download an extension's grade badge as an SVG image

        Example:

        ![xk6-sql](https://registry.k6.io/module/github.com/grafana/xk6-sql/grade.svg)
      operationId: getGradeBadge
      parameters:
        - $ref: "#/components/parameters/module"
      produces:
        - image/svg+xml
      responses:
        "200":
          description: successful operation
        "404":
          description: module not found
  /product/{product}.json:
    get:
      tags:
        - subset
      summary: Suubset by product
      description: Querying the subset of the registry containing the extensions available in the product specified in the parameter
      operationId: subsetByProduct
      parameters:
        - $ref: "#/components/parameters/product"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: product not found
  /product/{product}-catalog.json:
    get:
      tags:
        - catalog
      summary: Catalog by product
      description: Query the catalog containing extensions available in a given product.
      operationId: catalogByProduct
      parameters:
        - $ref: "#/components/parameters/product"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/catalog"
        "404":
          description: product not found
  /tier/{tier}.json:
    get:
      tags:
        - subset
      summary: Subset by support
      description: Querying the subset of the registry containing the extensions with support specified in the parameter
      operationId: subsetByTier
      parameters:
        - $ref: "#/components/parameters/tier"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: tier not found
  /tier/{tier}-catalog.json:
    get:
      tags:
        - catalog
      summary: Catalog by support
      description: Query the catalog containing extensions available with a given support.
      operationId: catalogByTier
      parameters:
        - $ref: "#/components/parameters/tier"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/catalog"
        "404":
          description: tier not found
  /tier/{tier}-metrics.json:
    get:
      tags:
        - metrics
      summary: Subset of registry metrics for tier.
      description: Download the registry metrics for tier as a single JSON file
      operationId: getTierMetrics
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/metrics"
  /tier/at-least/{tier}.json:
    get:
      tags:
        - subset
      summary: Subset by min support
      description: Query the subset of the registry that contains the extensions whose support is at least the level specified as a parameter.
      operationId: subsetByMinTier
      parameters:
        - $ref: "#/components/parameters/tier"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: tier not found
  /tier/at-least/{tier}-catalog.json:
    get:
      tags:
        - catalog
      summary: Catalog by min support
      description: Query the catalog containing extensions available with at least the support specified as a parameter.
      operationId: catalogByMinTier
      parameters:
        - $ref: "#/components/parameters/tier"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/catalog"
        "404":
          description: tier not found
  /category/{category}.json:
    get:
      tags:
        - subset
      summary: Subset by category
      description: Querying the subset of the registry containing extensions belonging to the category specified in the parameter
      operationId: subsetByCategory
      parameters:
        - $ref: "#/components/parameters/category"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: category not found
  /grade/{grade}.json:
    get:
      tags:
        - subset
      summary: Subset by grade
      description: Querying the subset of the registry containing the extensions with the compliance grade specified in the parameter
      operationId: subsetByGrade
      parameters:
        - $ref: "#/components/parameters/grade"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: grade not found
  /grade/at-least/{grade}.json:
    get:
      tags:
        - subset
      summary: Subset by min grade
      description: Querying the subset of the registry containing extensions with at least compliance grade specified in the parameter
      operationId: subsetByMinGrade
      parameters:
        - $ref: "#/components/parameters/grade"
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "registry.schema.json#/$defs/registry"
        "404":
          description: grade not found

components:
  parameters:
    module:
      in: path
      name: module
      required: true
      description: go module path of the extension
      examples:
        xk6-dashboard:
          value: "github.com/grafana/xk6-dashboard"
        xk6-sql:
          value: "github.com/grafana/xk6-sql"
      schema:
        type: string
    grade:
      in: path
      name: grade
      required: true
      description: grade to be queried
      examples:
        A:
          value: "A"
        C:
          value: "C"
      schema:
        $ref: "registry.schema.json#/$defs/grade"
    category:
      in: path
      name: category
      required: true
      description: category to be queried
      example: "data"
      schema:
        $ref: "registry.schema.json#/$defs/category"
    tier:
      in: path
      name: tier
      required: true
      description: tier to be queried
      examples:
        official:
          value: "official"
        community:
          value: "community"
      schema:
        $ref: "registry.schema.json#/$defs/tier"
    product:
      in: path
      name: product
      required: true
      description: product to be queried
      examples:
        oss:
          value: "oss"
        cloud:
          value: "cloud"
      schema:
        $ref: "registry.schema.json#/$defs/product"