APIs.io Engineering Platform
APIs.io Engineering Platform Dependency-Graph API

Endpoints to access Dependency Graph features.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  version: "1.0.0"
  x-release: v4
  title: APIs.io Engineering Platform Amazon API Gateway 2014 11 13 Dependency-Graph API
  description: <fullname>Amazon API Gateway</fullname> <p>Amazon API Gateway helps developers deliver robust, secure, and scalable mobile and web application back ends. API Gateway allows developers to securely connect mobile and web applications to APIs that run on AWS Lambda, Amazon EC2, or other publicly addressable web services that are hosted outside of AWS.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: apigateway
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/apigateway-2015-07-09.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: https://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: http://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
- url: https://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: Dependency-Graph
  description: Endpoints to access Dependency Graph features.
paths:
  /repos/{owner}/{repo}/dependency-graph/compare/{basehead}:
    get:
      summary: APIs.io Engineering Platform Get a diff of the dependencies between commits
      description: Gets the diff of the dependency changes between two commits of a repository, based on the changes to the dependency manifests made in those commits.
      tags:
      - Dependency-Graph
      operationId: dependency-graph/diff-range
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/dependency-graph/dependency-review#get-a-diff-of-the-dependencies-between-commits
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: basehead
        description: The base and head Git revisions to compare. The Git revisions will be resolved to commit SHAs. Named revisions will be resolved to their corresponding HEAD commits, and an appropriate merge base will be determined. This parameter expects the format `{base}...{head}`.
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/manifest-path'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dependency-graph-diff'
              examples:
                default:
                  $ref: '#/components/examples/diff-range-response'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '404':
          $ref: '#/components/responses/not_found'
        '403':
          $ref: '#/components/responses/dependency_review_forbidden'
      x-github:
        githubCloudOnly: false
        category: dependency-graph
        subcategory: dependency-review
  /repos/{owner}/{repo}/dependency-graph/sbom:
    get:
      summary: APIs.io Engineering Platform Export a software bill of materials (SBOM) for a repository.
      description: Exports the software bill of materials (SBOM) for a repository in SPDX JSON format.
      tags:
      - Dependency-Graph
      operationId: dependency-graph/export-sbom
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/dependency-graph/sboms#export-a-software-bill-of-materials-sbom-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dependency-graph-spdx-sbom'
              examples:
                default:
                  $ref: '#/components/examples/dependency-graph-export-sbom-response'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '404':
          $ref: '#/components/responses/not_found'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: false
        category: dependency-graph
        subcategory: sboms
  /repos/{owner}/{repo}/dependency-graph/snapshots:
    post:
      summary: APIs.io Engineering Platform Create a snapshot of dependencies for a repository
      description: 'Create a new snapshot of a repository''s dependencies.


        The authenticated user must have access to the repository.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Dependency-Graph
      operationId: dependency-graph/create-repository-snapshot
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/dependency-graph/dependency-submission#create-a-snapshot-of-dependencies-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/snapshot'
            examples:
              example-of-a-dependency-submission:
                $ref: '#/components/examples/dependency-graph-create-snapshot-request'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - created_at
                - result
                - message
                properties:
                  id:
                    type: integer
                    description: ID of the created snapshot.
                  created_at:
                    type: string
                    description: The time at which the snapshot was created.
                  result:
                    type: string
                    description: Either "SUCCESS", "ACCEPTED", or "INVALID". "SUCCESS" indicates that the snapshot was successfully created and the repository's dependencies were updated. "ACCEPTED" indicates that the snapshot was successfully created, but the repository's dependencies were not updated. "INVALID" indicates that the snapshot was malformed.
                  message:
                    type: string
                    description: A message providing further details about the result, such as why the dependencies were not updated.
              examples:
                example-of-a-dependency-submission:
                  $ref: '#/components/examples/dependency-graph-create-snapshot-success'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: dependency-graph
        subcategory: dependency-submission
components:
  responses:
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    dependency_review_forbidden:
      description: Response if GitHub Advanced Security is not enabled for this repository
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  schemas:
    manifest:
      type: object
      properties:
        name:
          type: string
          description: The name of the manifest.
          example: package-lock.json
        file:
          type: object
          properties:
            source_location:
              type: string
              description: The path of the manifest file relative to the root of the Git repository.
              example: /src/build/package-lock.json
          additionalProperties: false
        metadata:
          $ref: '#/components/schemas/metadata'
        resolved:
          type: object
          description: A collection of resolved package dependencies.
          additionalProperties:
            $ref: '#/components/schemas/dependency'
      required:
      - name
      additionalProperties: false
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    metadata:
      title: metadata
      description: User-defined metadata to store domain-specific information limited to 8 keys with scalar values.
      type: object
      maxProperties: 8
      additionalProperties:
        nullable: true
        anyOf:
        - type: string
        - type: number
        - type: boolean
    dependency-graph-spdx-sbom:
      title: Dependency Graph SPDX SBOM
      description: A schema for the SPDX JSON format returned by the Dependency Graph.
      type: object
      properties:
        sbom:
          type: object
          properties:
            SPDXID:
              type: string
              example: SPDXRef-DOCUMENT
              description: The SPDX identifier for the SPDX document.
            spdxVersion:
              type: string
              example: SPDX-2.3
              description: The version of the SPDX specification that this document conforms to.
            creationInfo:
              type: object
              properties:
                created:
                  type: string
                  example: '2021-11-03T00:00:00Z'
                  description: The date and time the SPDX document was created.
                creators:
                  type: array
                  items:
                    type: string
                    example: GitHub
                  description: The tools that were used to generate the SPDX document.
              required:
              - created
              - creators
            name:
              type: string
              example: github/github
              description: The name of the SPDX document.
            dataLicense:
              type: string
              example: CC0-1.0
              description: The license under which the SPDX document is licensed.
            documentDescribes:
              type: array
              items:
                type: string
                example: github/github
              description: The name of the repository that the SPDX document describes.
            documentNamespace:
              type: string
              example: https://github.com/example/dependency_graph/sbom-123
              description: The namespace for the SPDX document.
            packages:
              type: array
              items:
                type: object
                properties:
                  SPDXID:
                    type: string
                    example: SPDXRef-Package
                    description: A unique SPDX identifier for the package.
                  name:
                    type: string
                    example: rubygems:github/github
                    description: The name of the package.
                  versionInfo:
                    type: string
                    example: 1.0.0
                    description: 'The version of the package. If the package does not have an exact version specified,

                      a version range is given.'
                  downloadLocation:
                    type: string
                    example: NOASSERTION
                    description: 'The location where the package can be downloaded,

                      or NOASSERTION if this has not been determined.'
                  filesAnalyzed:
                    type: boolean
                    example: false
                    description: 'Whether the package''s file content has been subjected to

                      analysis during the creation of the SPDX document.'
                  licenseConcluded:
                    type: string
                    example: MIT
                    description: The license of the package as determined while creating the SPDX document.
                  licenseDeclared:
                    type: string
                    example: NOASSERTION
                    description: 'The license of the package as declared by its author, or NOASSERTION if this information

                      was not available when the SPDX document was created.'
                  supplier:
                    type: string
                    example: NOASSERTION
                    description: The distribution source of this package, or NOASSERTION if this was not determined.
                  copyrightText:
                    type: string
                    example: Copyright (c) 1985 GitHub.com
                    description: The copyright holders of the package, and any dates present with those notices, if available.
                  externalRefs:
                    type: array
                    items:
                      type: object
                      properties:
                        referenceCategory:
                          type: string
                          example: PACKAGE-MANAGER
                          description: The category of reference to an external resource this reference refers to.
                        referenceLocator:
                          type: string
                          example: pkg:gem/rails@6.0.1
                          description: A locator for the particular external resource this reference refers to.
                        referenceType:
                          type: string
                          example: purl
                          description: The category of reference to an external resource this reference refers to.
                      required:
                      - referenceCategory
                      - referenceLocator
                      - referenceType
              required:
              - SPDXID
              - name
              - versionInfo
              - downloadLocation
              - filesAnalyzed
              - licenseConcluded
              - licenseDeclared
              - supplier
          required:
          - SPDXID
          - spdxVersion
          - creationInfo
          - name
          - dataLicense
          - documentDescribes
          - documentNamespace
          - packages
      required:
      - sbom
    dependency:
      type: object
      properties:
        package_url:
          type: string
          description: Package-url (PURL) of dependency. See https://github.com/package-url/purl-spec for more details.
          example: pkg:/npm/%40actions/http-client@1.0.11
          pattern: ^pkg
        metadata:
          $ref: '#/components/schemas/metadata'
        relationship:
          type: string
          description: A notation of whether a dependency is requested directly by this manifest or is a dependency of another dependency.
          example: direct
          enum:
          - direct
          - indirect
        scope:
          type: string
          description: A notation of whether the dependency is required for the primary build artifact (runtime) or is only used for development. Future versions of this specification may allow for more granular scopes.
          example: runtime
          enum:
          - runtime
          - development
        dependencies:
          type: array
          description: Array of package-url (PURLs) of direct child dependencies.
          example: '@actions/http-client'
          items:
            type: string
      additionalProperties: false
    snapshot:
      title: snapshot
      description: Create a new snapshot of a repository's dependencies.
      type: object
      properties:
        version:
          description: The version of the repository snapshot submission.
          type: integer
        job:
          type: object
          properties:
            id:
              type: string
              description: The external ID of the job.
              example: 5622a2b0-63f6-4732-8c34-a1ab27e102a11
            correlator:
              type: string
              description: Correlator provides a key that is used to group snapshots submitted over time. Only the "latest" submitted snapshot for a given combination of `job.correlator` and `detector.name` will be considered when calculating a repository's current dependencies. Correlator should be as unique as it takes to distinguish all detection runs for a given "wave" of CI workflow you run. If you're using GitHub Actions, a good default value for this could be the environment variables GITHUB_WORKFLOW and GITHUB_JOB concatenated together. If you're using a build matrix, then you'll also need to add additional key(s) to distinguish between each submission inside a matrix variation.
              example: yourworkflowname_yourjobname
            html_url:
              type: string
              description: The url for the job.
              example: http://example.com/build
          required:
          - id
          - correlator
          additionalProperties: false
        sha:
          description: 'The commit SHA associated with this dependency snapshot. Maximum length: 40 characters.'
          type: string
          example: ddc951f4b1293222421f2c8df679786153acf689
          minLength: 40
          maxLength: 40
        ref:
          description: The repository branch that triggered this snapshot.
          type: string
          pattern: ^refs/
          example: refs/heads/main
        detector:
          type: object
          description: A description of the detector used.
          properties:
            name:
              type: string
              description: The name of the detector used.
              example: docker buildtime detector
            version:
              type: string
              description: The version of the detector used.
              example: 1.0.0
            url:
              type: string
              description: The url of the detector used.
              example: http://example.com/docker-buildtimer-detector
          required:
          - name
          - version
          - url
          additionalProperties: false
        metadata:
          $ref: '#/components/schemas/metadata'
        manifests:
          type: object
          description: A collection of package manifests, which are a collection of related dependencies declared in a file or representing a logical group of dependencies.
          additionalProperties:
            $ref: '#/components/schemas/manifest'
        scanned:
          type: string
          format: date-time
          description: The time at which the snapshot was scanned.
          example: '2020-06-13T14:52:50-05:00'
      required:
      - detector
      - version
      - ref
      - sha
      - job
      - scanned
      additionalProperties: false
    dependency-graph-diff:
      title: Dependency Graph Diff
      description: A diff of the dependencies between two commits.
      type: array
      items:
        type: object
        properties:
          change_type:
            type: string
            enum:
            - added
            - removed
          manifest:
            type: string
            example: path/to/package-lock.json
          ecosystem:
            type: string
            example: npm
          name:
            type: string
            example: '@actions/core'
          version:
            type: string
            example: 1.0.0
          package_url:
            type: string
            nullable: true
            example: pkg:/npm/%40actions/core@1.1.0
          license:
            type: string
            nullable: true
            example: MIT
          source_repository_url:
            type: string
            nullable: true
            example: https://github.com/github/actions
          vulnerabilities:
            type: array
            items:
              type: object
              properties:
                severity:
                  type: string
                  example: critical
                advisory_ghsa_id:
                  type: string
                  example: GHSA-rf4j-j272-fj86
                advisory_summary:
                  type: string
                  example: A summary of the advisory.
                advisory_url:
                  type: string
                  example: https://github.com/advisories/GHSA-rf4j-j272-fj86
              required:
              - severity
              - advisory_ghsa_id
              - advisory_summary
              - advisory_url
          scope:
            description: Where the dependency is utilized. `development` means that the dependency is only utilized in the development environment. `runtime` means that the dependency is utilized at runtime and in the development environment.
            type: string
            enum:
            - unknown
            - runtime
            - development
        required:
        - change_type
        - manifest
        - ecosystem
        - name
        - version
        - package_url
        - license
        - source_repository_url
        - vulnerabilities
        - scope
  examples:
    dependency-graph-create-snapshot-success:
      value:
        id: 12345
        created_at: '2018-05-04T01:14:52Z'
        message: Dependency results for the repo have been successfully updated.
        result: SUCCESS
    diff-range-response:
      value:
      - change_type: removed
        manifest: package.json
        ecosystem: npm
        name: helmet
        version: 4.6.0
        package_url: pkg:npm/helmet@4.6.0
        license: MIT
        source_repository_url: https://github.com/helmetjs/helmet
        vulnerabilities: []
      - change_type: added
        manifest: package.json
        ecosystem: npm
        name: helmet
        version: 5.0.0
        package_url: pkg:npm/helmet@5.0.0
        license: MIT
        source_repository_url: https://github.com/helmetjs/helmet
        vulnerabilities: []
      - change_type: added
        manifest: Gemfile
        ecosystem: rubygems
        name: ruby-openid
        version: 2.7.0
        package_url: pkg:gem/ruby-openid@2.7.0
        license: null
        source_repository_url: https://github.com/openid/ruby-openid
        vulnerabilities:
        - severity: critical
          advisory_ghsa_id: GHSA-fqfj-cmh6-hj49
          advisory_summary: Ruby OpenID
          advisory_url: https://github.com/advisories/GHSA-fqfj-cmh6-hj49
    dependency-graph-create-snapshot-request:
      value:
        version: 0
        sha: ce587453ced02b1526dfb4cb910479d431683101
        ref: refs/heads/main
        job:
          correlator: yourworkflowname_youractionname
          id: yourrunid
        detector:
          name: octo-detector
          version: 0.0.1
          url: https://github.com/octo-org/octo-repo
        scanned: '2022-06-14T20:25:00Z'
        manifests:
          package-lock.json:
            name: package-lock.json
            file:
              source_location: src/package-lock.json
            resolved:
              '@actions/core':
                package_url: pkg:/npm/%40actions/core@1.1.9
                dependencies:
                - '@actions/http-client'
              '@actions/http-client':
                package_url: pkg:/npm/%40actions/http-client@1.0.7
                dependencies:
                - tunnel
              tunnel:
                package_url: pkg:/npm/tunnel@0.0.6
    dependency-graph-export-sbom-response:
      value:
        sbom:
          SPDXID: SPDXRef-DOCUMENT
          spdxVersion: SPDX-2.3
          creationInfo:
            created: '2021-09-01T00:00:00Z'
            creators:
            - 'Tool: GitHub.com-Dependency-Graph'
          name: github/example
          dataLicense: CC0-1.0
          documentDescribes:
          - github/example
          documentNamespace: https://github.com/github/example/dependency_graph/sbom-abcdef123456
          packages:
          - SPDXID: SPDXRef-Package
            name: rubygems:rails
            versionInfo: 1.0.0
            downloadLocation: NOASSERTION
            filesAnalyzed: false
            licenseConcluded: NOASSERTION
            licenseDeclared: NOASSERTION
  parameters:
    repo:
      name: repo
      description: The name of the repository without the `.git` extension. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    owner:
      name: owner
      description: The account owner of the repository. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    manifest-path:
      name: name
      description: The full path, relative to the repository root, of the dependency manifest file.
      in: query
      required: false
      schema:
        type: string
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  securitySchemes:
    hmac:
      type: apiKey
      name: Authorization
      in: header
      description: Amazon Signature authorization v4
      x-amazon-apigateway-authtype: awsSigv4
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/apigateway/
x-hasEquivalentPaths: true
APIs.io Engineering Platform Dependency-Graph API

Documentation

Specifications

Other Resources

OpenAPI Specification
