openapi: 3.2.0
info:
  title: CollectOSS REST Risk API
  version: 0.60.0
host: example.com
basePath: /api/unstable/
tags:
- name: Risk
paths:
  /metadata/repo_info:
    get:
      description: Returns the metadata about all repositories in a CollectOSS instance, using information from a git platform (GitHub, GitLab, etc.). Each record includes the default branch, forks, stars, watchers, and committers. Also includes metadata about current repository issue and pull request status and counts.
      operationId: ActivityMetadata(Repo)
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                repo_git:
                  description: 'Example: https://github.com/chaoss/collectoss'
                  type: string
                repo_name:
                  description: 'Example: collectoss'
                  type: string
                repo_id:
                  description: 'Example: 25540'
                  type: integer
                default_branch:
                  description: 'Example: Main'
                  type: string
                license:
                  description: 'Example: MIT'
                  type: string
                fork_count:
                  description: 'Example: 554'
                  type: integer
                watchers_count:
                  description: 'Example: 424'
                  type: integer
                stars_count:
                  description: 'Example: 443'
                  type: integer
                commits_count:
                  description: '4434'
                  type: integer
                committers_count:
                  description: 'Example: 42'
                  type: integer
                open_issues:
                  description: 'Example: 7'
                  type: integer
                issues_count:
                  description: 'Example: 23332'
                  type: integer
                issues_closed:
                  description: 'Example: 23322'
                  type: integer
                pull_request_count:
                  description: 'Example: 19445'
                  type: integer
                pull_requests_open:
                  description: 'Example: 10'
                  type: integer
                pull_requests_closed:
                  description: 'Example: 19435'
                  type: integer
                pull_requests_merged:
                  description: 'Example: 17473'
                  type: integer
            type: array
      tags:
      - Risk
      summary: Activity metadata (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Activity Metadata (Repo)
  /metadata/contributions_count:
    get:
      description: 'Returns a list of repositories contributed to by all the contributors in a CollectOSS Instance: INCLUDING all repositories on a platform, *not* merely those repositories in the CollectOSS Instance. Numerical totals represent total CONTRIBUTIONS.'
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-contributors/
      operationId: ContributionsCount(Repo)
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                repo_git:
                  description: 'Example: https://github.com/chaoss/collectoss'
                  type: string
                contributions:
                  description: 'Example: 43301'
                  type: integer
            type: array
      tags:
      - Risk
      summary: Contributions count (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Contributions Count (Repo)
  /metadata/contributors_count:
    get:
      description: 'Returns a list of repositories contributed to by all the contributors in a CollectOSS Instance: INCLUDING all repositories on a platform, *not* merely those repositories in the CollectOSS Instance. Numerical totals represent total CONTRIBUTORS.'
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-contributors/
      operationId: ContributorsCount(Repo)
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                repo_git:
                  description: 'Example: https://github.com/chaoss/collectoss'
                  type: string
                contributors:
                  description: 'Example: 77'
                  type: integer
            type: array
      tags:
      - Risk
      summary: Contributors count (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Contributors Count (Repo)
  /repo-groups/:repo_group_id/average-issue-resolution-time:
    get:
      description: The average issue resolution time.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-issue-resolution-duration/
      operationId: AverageIssueResolutionTime(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                avg_issue_resolution_time:
                  description: 'Example: 1413 days 15:39:48'
                  type: string
                repo_id:
                  description: 'Example: 21353'
                  type: integer
                repo_name:
                  description: 'Example: open_id_authentication'
                  type: string
            type: array
      tags:
      - Risk
      summary: Average issue resolution time (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Average Issue Resolution Time (Repo Group)
  /repos/:repo_id/average-issue-resolution-time:
    get:
      description: The average issue resolution time.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-issue-resolution-duration/
      operationId: AverageIssueResolutionTime(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                avg_issue_resolution_time:
                  description: 'Example: 276 days 13:54:13.2'
                  type: string
                repo_name:
                  description: 'Example: maven-release'
                  type: string
            type: array
      tags:
      - Risk
      summary: Average issue resolution time (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Average Issue Resolution Time (Repo)
  /repo-groups/:repo_group_id/cii-best-practices-badge:
    get:
      description: The CII Best Practices Badge level.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-open-source-security-foundation-openssf-best-practices-badge/
      operationId: CIIBestPracticesBadge(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                badge_level:
                  description: 'Example: in_progress'
                  type: string
                repo_id:
                  description: 'Example: 21252'
                  type: integer
                repo_name:
                  description: 'Example: php-legal-licenses'
                  type: string
            type: array
      tags:
      - Risk
      summary: CII best practices badge (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: CII Best Practices Badge (Repo Group)
  /repos/:repo_id/cii-best-practices-badge:
    get:
      description: The CII Best Practices Badge level.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-open-source-security-foundation-openssf-best-practices-badge/
      operationId: CIIBestPracticesBadge(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                badge_level:
                  description: 'Example: passing'
                  type: string
                repo_name:
                  description: 'Example: trickster'
                  type: string
            type: array
      tags:
      - Risk
      summary: CII best practices badge (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: CII Best Practices Badge (Repo)
  /repo-groups/:repo_group_id/committers:
    get:
      description: Number of persons opening an issue for the first time.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-committers/
      operationId: Committers(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      - description: Periodicity specification.
        in: path
        name: period
        schema:
          type: string
        type: string
      - description: 'Beginning date specification. E.g. values: 2018, 2018-05, 2019-05-01'
        in: path
        name: begin_date
        schema:
          type: string
        type: string
      - description: 'Ending date specification. E.g. values: 2018, 2018-05, 2019-05-01'
        in: path
        name: end_date
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                count:
                  description: 'Example: 372'
                  type: integer
                date:
                  description: 'Example: 2007-01-01T00:00:00.000Z'
                  type: string
                rg_name:
                  description: 'Example: Comcast'
                  type: string
            type: array
      tags:
      - Risk
      summary: Committers (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Committers (Repo Group)
  /repos/:repo_id/committers:
    get:
      description: Number of persons contributing with an accepted commit for the first time.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-committers/
      operationId: Committers(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      - description: Periodicity specification.
        in: path
        name: period
        schema:
          type: string
        type: string
      - description: 'Beginning date specification. E.g. values: 2018, 2018-05, 2019-05-01'
        in: path
        name: begin_date
        schema:
          type: string
        type: string
      - description: 'Ending date specification. E.g. values: 2018, 2018-05, 2019-05-01'
        in: path
        name: end_date
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                count:
                  description: 'Example: 1'
                  type: integer
                date:
                  description: 'Example: 2018-10-25T00:00:00.000Z'
                  type: string
                repo_name:
                  description: 'Example: weasel'
                  type: string
                rg_name:
                  description: 'Example: Comcast'
                  type: string
            type: array
      tags:
      - Risk
      summary: Committers (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Committers (Repo)
  /repo-groups/:repo_group_id/fork-count:
    get:
      description: A technical fork is a distributed version control copy of a project. The number of technical forks indicates the number of copies of a project on the same code development platform.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-technical-fork/
      operationId: ForkCount(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                forks:
                  description: 'Example: 4'
                  type: integer
                repo_id:
                  description: 'Example: 21364'
                  type: integer
                repo_name:
                  description: 'Example: irs_process_scripts'
                  type: string
            type: array
      tags:
      - Risk
      summary: Fork count (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Fork Count (Repo Group)
  /repos/:repo_id/fork-count:
    get:
      description: A technical fork is a distributed version control copy of a project. The number of technical forks indicates the number of copies of a project on the same code development platform.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-technical-fork/
      operationId: ForkCount(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                forks:
                  description: 'Example: 844'
                  type: integer
                repo_name:
                  description: 'Example: graphiql'
                  type: string
            type: array
      tags:
      - Risk
      summary: Fork count (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Fork Count (Repo)
  /repo-groups/:repo_group_id/forks:
    get:
      description: A time series of fork count.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-technical-fork/
      operationId: Forks(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                date:
                  description: 'Example: 2019-07-03T23:26:42.000Z'
                  type: string
                forks:
                  description: 'Example: 519'
                  type: integer
                repo_id:
                  description: 'Example: 21036'
                  type: integer
                repo_name:
                  description: 'Example: jquery-ujs'
                  type: string
            type: array
      tags:
      - Risk
      summary: Forks (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Forks (Repo Group)
  /repos/:repo_id/forks:
    get:
      description: A time series of fork count.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-technical-fork/
      operationId: Forks(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                date:
                  description: 'Example: 2019-07-03T23:27:42.000Z'
                  type: string
                forks:
                  description: 'Example: 843'
                  type: integer
                repo_name:
                  description: 'Example: graphiql'
                  type: string
            type: array
      tags:
      - Risk
      summary: Forks (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Forks (Repo)
  /repo-groups/:repo_group_id/license-coverage:
    get:
      description: How much of the code base has declared licenses that scanners can recognize which may not be just OSI-approved. This includes both software and documentation source files and is represented as a percentage of total coverage.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-license-coverage/
      operationId: LicenseCoverage(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                coverage:
                  description: 'Example: 0.373'
                  type: string
                license_declared_files:
                  description: 'Example: 19'
                  type: integer
                name:
                  description: 'Example: ActorServiceRegistry'
                  type: string
                total_files:
                  description: 'Example: 51'
                  type: integer
            type: array
      tags:
      - Risk
      summary: License coverage (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Coverage (Repo Group)
  /repos/:repo_id/license-coverage:
    get:
      description: How much of the code base has declared licenses that scanners can recognize which may not be just OSI-approved. This includes both software and documentation source files and is represented as a percentage of total coverage.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-license-coverage/
      operationId: LicenseCoverage(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                coverage:
                  description: 'Example: 0.347'
                  type: string
                license_declared_file:
                  description: 'Example: 33'
                  type: integer
                repo_name:
                  description: 'Example: zucchini'
                  type: string
                total_files:
                  description: 'Example: 95'
                  type: integer
            type: array
      tags:
      - Risk
      summary: License coverage (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Coverage (Repo)
  /repo-groups/:repo_group_id/license-declared:
    get:
      description: The total number and specific licenses declared in a software package. This can include both software and documentation source files. This metric is an enumeration of licenses, and the number of files with that particular license declaration.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-licenses-declared/
      operationId: LicenseDeclared(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                name:
                  description: 'Example: trickster'
                  type: string
                note:
                  description: 'Example: '
                  type: string
                short_name:
                  description: 'Example: Apache-2.0'
                  type: string
            type: array
      tags:
      - Risk
      summary: License declared (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Declared (Repo Group)
  /repos/:repo_id/license-declared:
    get:
      description: The total number and specific licenses declared in a software package. This can include both software and documentation source files. This metric is an enumeration of licenses, and the number of files with that particular license declaration.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-licenses-declared/
      operationId: LicenseDeclared(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                name:
                  description: 'Example: trickster'
                  type: string
                note:
                  description: 'Example: '
                  type: string
                short_name:
                  description: 'Example: Apache-2.0'
                  type: string
            type: array
      tags:
      - Risk
      summary: License declared (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Declared (Repo)
  /repo-groups/:repo_group_id/languages:
    get:
      description: The primary language of the repository.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-programming-language-distribution/
      operationId: Languages(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                primary_language:
                  description: 'Example: Go'
                  type: string
                repo_id:
                  description: 'Example: 21277'
                  type: integer
            type: array
      tags:
      - Risk
      summary: Languages (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Languages (Repo Group)
  /repo-groups/:repo_id/languages:
    get:
      description: The primary language of the repository.
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-programming-language-distribution/
      operationId: Languages(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                primary_language:
                  description: 'Example: Go'
                  type: string
                repo_id:
                  description: 'Example: 21277'
                  type: integer
            type: array
      tags:
      - Risk
      summary: Languages (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: Languages (Repo)
  /repo-groups/:repo_group_id/license-count:
    get:
      description: The declared software package license (fetched from CII Best Practices badging data).
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-osi-approved-licenses/
      operationId: LicenseCount(RepoGroup)
      parameters:
      - description: Repository Group ID
        in: path
        name: repo_group_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                file_without_licenses:
                  description: 'Example: True'
                  type: string
                name:
                  description: 'Example: ActorServiceRegistry'
                  type: string
                number_of_license:
                  description: 'Example: 2'
                  type: integer
            type: array
      tags:
      - Risk
      summary: License count (repo group)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Count (Repo Group)
  /repo-groups/:repo_id/license-count:
    get:
      description: The declared software package license (fetched from CII Best Practices badging data).
      externalDocs:
        description: CHAOSS Metric Definition
        url: https://chaoss.community/kb/metric-osi-approved-licenses/
      operationId: LicenseCount(Repo)
      parameters:
      - description: Repository ID.
        in: path
        name: repo_id
        schema:
          type: string
        type: string
      responses:
        '200':
          description: OK
          schema:
            items:
              properties:
                file_without_licenses:
                  description: 'Example: True'
                  type: string
                name:
                  description: 'Example: ActorServiceRegistry'
                  type: string
                number_of_license:
                  description: 'Example: 2'
                  type: integer
            type: array
      tags:
      - Risk
      summary: License count (repo)
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: License Count (Repo)
externalDocs:
  description: CHAOSS Metric Definitions
  url: https://chaoss.community/kb-metrics-and-metrics-models/