### GetPackage Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates fetching package details via the v3 gRPC service. This example uses grpcurl for command-line interaction.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetPackage \ 
  -d '{"packageKey": {"system": "NPM", "name": "react"}}'
```

--------------------------------

### Go Client: Basic Setup and GetPackage Request

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

Demonstrates the basic setup for a Go gRPC client, including creating TLS credentials, connecting to the service, and making a GetPackage request. This code snippet shows how to initialize the client and perform the initial request.

```go
package main

import (
  "context"
  "fmt"
  "log"
  
  depsdev "deps.dev/api/v3"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
)

func main() {
  // Create TLS credentials
  creds, err := credentials.NewClientTLSFromFile("", "api.deps.dev")
  if err != nil {
    log.Fatalf("Failed to create credentials: %v", err)
  }
  
  // Connect to the service
  conn, err := grpc.Dial(
    "api.deps.dev:443",
    grpc.WithTransportCredentials(creds),
  )
  if err != nil {
    log.Fatalf("Failed to dial: %v", err)
  }
  defer conn.Close()
  
  // Create client
  client := depsdev.NewInsightsClient(conn)
  
  // Make request
  ctx := context.Background()
  resp, err := client.GetPackage(ctx, &depsdev.GetPackageRequest{
    PackageKey: &depsdev.PackageKey{
      System: depsdev.System_NPM,
      Name:   "react",
    },
  })
  if err != nil {
    log.Fatalf("GetPackage failed: %v", err)
  }
  
  fmt.Printf("Package: %s\n", resp.PackageKey.Name)
  fmt.Printf("Versions: %d\n", len(resp.Versions))
}
```

--------------------------------

### NuGet Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the NuGet system.

```json
{
  "system": "NUGET",
  "name": "Newtonsoft.Json"
}
```

--------------------------------

### Install grpcurl

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

Install the grpcurl command-line tool for testing gRPC services. This is a prerequisite for CLI testing.

```bash
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
```

--------------------------------

### Maven Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of Maven parent, dependencies, and properties.

```json
{
  "maven": {
    "parent": {
      "system": "MAVEN",
      "name": "org.springframework:spring-framework-bom",
      "version": "5.2.0.RELEASE"
    },
    "dependencies": [
      {
        "name": "org.springframework:spring-core",
        "version": "[5.2, 6.0)",
        "type": "jar",
        "scope": "compile",
        "optional": "false"
      }
    ],
    "properties": [
      {
        "name": "project.version",
        "value": "1.0.0"
      }
    ]
  }
}
```

--------------------------------

### gRPC API Usage

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

A client reference guide for the gRPC API, including setup, grpcurl examples, Go client library details, and coverage of v3alpha extension methods.

```APIDOC
## gRPC API Usage

### Description
This guide serves as a reference for gRPC clients interacting with the deps.dev API. It includes setup instructions, command-line testing examples using grpcurl, detailed Go client library examples, and explanations of v3alpha extension methods.

### Key Topics
- Setup and prerequisites
- grpcurl command-line testing examples
- Complete Go client library examples
- All service methods with Go code examples
- v3alpha extension methods (batch operations, findings, etc.)
- Error handling with gRPC status codes
- Pagination for batch endpoints
- Context and timeouts
- Performance tips
```

--------------------------------

### GetProject Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching project details through the v3 gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetProject \ 
  -d '{"projectKey": {"host": "github.com", "name": "facebook/react"}}'
```

--------------------------------

### PyPI Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the PyPI system.

```json
{
  "system": "PYPI",
  "name": "django"
}
```

--------------------------------

### Go gRPC Client Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Provides a complete example of a Go gRPC client interacting with the deps.dev v3 service. This demonstrates setting up the client and calling methods.

```go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"deps.dev/api/v3/deps"
)

func main() {
	conn, err := grpc.Dial("localhost:8080", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()

	c := deps.NewApiServiceClien(conn)

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	resp, err := c.GetPackage(ctx, &deps.GetPackageRequest{
		PackageKey: &deps.PackageKey{
			System: deps.PackageKey_NPM,
			Name:   "react",
		},
	})
	if err != nil {
		log.Fatalf("%v. GetPackage failed: %v", ctx.Value("request-id"), err)
	}
	log.Printf("Package Name: %s", resp.Package.Name)
}
```

--------------------------------

### GetVersion Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates retrieving version details through the v3 gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetVersion \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### GetCapabilities Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching capabilities for a package version via the v3alpha gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetCapabilities \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### Cargo Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of Cargo dependencies and features.

```json
{
  "cargo": {
    "dependencies": [
      {
        "name": "serde",
        "requirement": "1.0",
        "kind": "normal",
        "optional": false,
        "uses_default_features": true,
        "features": ["derive"]
      },
      {
        "name": "tokio",
        "requirement": "1.0",
        "kind": "dev",
        "optional": false
      }
    ],
    "features": [
      {
        "name": "default",
        "implies": ["std"]
      }
    ]
  }
}
```

--------------------------------

### Cargo Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the Cargo system.

```json
{
  "system": "CARGO",
  "name": "tokio"
}
```

--------------------------------

### Complete Example: Dependency Analyzer

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

A full example demonstrating how to use the deps.dev gRPC API to analyze package dependencies. It includes setting up the client, fetching package and version details, and counting direct dependencies.

```go
package main

import (
  "context"
  "fmt"
  "log"
  "time"
  
  depsdev "deps.dev/api/v3"
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
)

func main() {
  creds, _ := credentials.NewClientTLSFromFile("", "api.deps.dev")
  conn, _ := grpc.Dial("api.deps.dev:443", grpc.WithTransportCredentials(creds))
  defer conn.Close()
  
  client := depsdev.NewInsightsClient(conn)
  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
  defer cancel()
  
  // Get package info
  pkg, _ := client.GetPackage(ctx, &depsdev.GetPackageRequest{
    PackageKey: &depsdev.PackageKey{System: depsdev.System_NPM, Name: "express"},
  })
  
  if len(pkg.Versions) > 0 {
    latest := pkg.Versions[0]
    
    // Get version details
    version, _ := client.GetVersion(ctx, &depsdev.GetVersionRequest{
      VersionKey: latest.VersionKey,
    })
    
    fmt.Printf("Package: %s@%s\n", version.VersionKey.Name, version.VersionKey.Version)
    fmt.Printf("Licenses: %v\n", version.Licenses)
    fmt.Printf("Advisories: %d\n", len(version.AdvisoryKeys))
    
    // Get dependencies
    deps, _ := client.GetDependencies(ctx, &depsdev.GetDependenciesRequest{
      VersionKey: latest.VersionKey,
    })
    
    directDeps := 0
    for _, node := range deps.Nodes {
      if node.Relation == depsdev.DependencyRelation_DIRECT {
        directDeps++
      }
    }
    fmt.Printf("Direct dependencies: %d\n", directDeps)
  }
}
```

--------------------------------

### Maven Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the Maven system.

```json
{
  "system": "MAVEN",
  "name": "org.apache.commons:commons-lang3"
}
```

--------------------------------

### PyPI Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of PyPI dependencies, provided extras, and required Python version.

```json
{
  "pypi": {
    "dependencies": [
      {
        "project_name": "setuptools",
        "version_specifier": ">= 40",
        "environment_marker": ""
      },
      {
        "project_name": "sqlparse",
        "version_specifier": ">= 0.2.2",
        "environment_marker": ""
      }
    ],
    "provided_extras": [
      {
        "name": "bcrypt"
      },
      {
        "name": "argon2"
      }
    ],
    "required_python_version": ">=3.8"
  }
}
```

--------------------------------

### GetFindings Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve security findings for a package version via the v3alpha gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetFindings \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### Go Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the Go package management system. Used to uniquely identify a Go package.

```json
{
  "system": "GO",
  "name": "github.com/golang/go"
}
```

--------------------------------

### GetProjectPackageVersions Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates fetching package versions for a project via the v3 gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetProjectPackageVersions \ 
  -d '{"projectKey": {"host": "github.com", "name": "facebook/react"}}'
```

--------------------------------

### NuGet Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

An example JSON object illustrating NuGet package requirements for different target frameworks.

```json
{
  "nuget": {
    "dependency_groups": [
      {
        "target_framework": "net5.0",
        "dependencies": [
          {
            "name": "System.Net.Http",
            "requirement": "4.3.0"
          }
        ]
      },
      {
        "target_framework": "net6.0",
        "dependencies": [
          {
            "name": "System.Runtime",
            "requirement": "4.3.1"
          }
        ]
      }
    ],
    "target_frameworks": ["net5.0", "net6.0"],
    "development_dependency": false
  }
}
```

--------------------------------

### Query Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates querying for packages using the v3 gRPC service with grpcurl. Allows specifying systems and query strings.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/Query \ 
  -d '{"systems": ["NPM"], "query": "react"}'
```

--------------------------------

### GetRequirements Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates retrieving system-specific requirements for a package version via the v3 gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetRequirements \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### Go HTTP API Usage Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows a common workflow using the deps.dev HTTP API with Go. This example retrieves package dependencies.

```go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	resp, err := http.Get("https://api.deps.dev/v3/dependencies/npm/react@17.0.2")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(body))
}
```

--------------------------------

### GetAdvisory Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to fetch security advisory details for a package version via the v3 gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetAdvisory \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### PyPI Dependencies Schema Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/requirements-schema.md

Example JSON structure for defining Python package dependencies, including version specifiers and environment markers.

```json
{
  "pypi": {
    "dependencies": [
      {
        "project_name": "requests",
        "version_specifier": ">=2.25.0",
        "environment_marker": ""
      },
      {
        "project_name": "sqlalchemy",
        "version_specifier": ">=1.4,<2.0",
        "environment_marker": ""
      },
      {
        "project_name": "typing-extensions",
        "version_specifier": ">=3.7.4",
        "environment_marker": "python_version < '3.8'"
      }
    ],
    "provided_extras": [
      {"name": "dev"},
      {"name": "test"},
      {"name": "docs"}
    ],
    "external_dependencies": [
      {
        "name": "libpq-dev",
        "version_specifier": "",
        "environment_marker": "platform_system == 'Linux'"
      }
    ],
    "required_python_version": ">=3.7"
  }
}
```

--------------------------------

### Package URL (PURL) Examples

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Examples of Package URLs (PURLs) for various package systems including npm, golang, maven, pypi, nuget, cargo, and gem.

```text
pkg:npm/react@18.2.0
```

```text
pkg:npm/@babel/core@7.20.0
```

```text
pkg:golang/github.com/golang/go@v1.19.0
```

```text
pkg:maven/org.apache.commons/commons-lang3@3.12.0
```

```text
pkg:pypi/django@4.1.0
```

```text
pkg:nuget/newtonsoft.json@13.0.1
```

```text
pkg:cargo/tokio@1.25.0
```

```text
pkg:gem/rails@7.0.0
```

--------------------------------

### Install Go Client Libraries

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

Fetch the Go client libraries for the v3 and v3alpha versions of the deps.dev API. These are needed for programmatic access.

```bash
go get deps.dev/api/v3
go get deps.dev/api/v3alpha
```

--------------------------------

### JavaScript/Node.js HTTP API Usage Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates a common workflow using the deps.dev HTTP API with JavaScript/Node.js. This example fetches package information.

```javascript
const fetch = require('node-fetch');

async function getPackageInfo() {
  const response = await fetch('https://api.deps.dev/v3/package/npm/react');
  const data = await response.json();
  console.log(data);
}

getPackageInfo();
```

--------------------------------

### GetCapabilities Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve capabilities (e.g., supported features, licenses) for a package version using the v3alpha HTTP API.

```curl
curl "https://api.deps.dev/v3alpha/capabilities/npm/react@17.0.2"
```

--------------------------------

### RubyGems Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the RubyGems package management system. Used to uniquely identify a Ruby gem.

```json
{
  "system": "RUBYGEMS",
  "name": "rails"
}
```

--------------------------------

### Python HTTP API Usage Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates a common workflow using the deps.dev HTTP API with Python. This example shows how to fetch package dependencies.

```python
import requests

response = requests.get("https://api.deps.dev/v3/dependencies/npm/react@17.0.2")
print(response.json())
```

--------------------------------

### GetProjectBatch Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates retrieving multiple projects via the v3alpha gRPC service using grpcurl. Supports batching up to 5000 projects.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetProjectBatch \ 
  -d '{"projectKeys": [{"host": "github.com", "name": "facebook/react"}, {"host": "github.com", "name": "lodash/lodash"}]}'
```

--------------------------------

### GetRequirements Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching system-specific requirements for a package version using the v3 HTTP API. URL encoding is necessary.

```curl
curl "https://api.deps.dev/v3/requirements/npm/react@17.0.2"
```

--------------------------------

### GetDependencies Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to fetch dependency information for a package version using the v3 gRPC service with grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3.ApiService/GetDependencies \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### npm URL Encoding Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Illustrates how scoped npm package names need to be percent-encoded when used in URLs. For example, '@babel/core' becomes '%40babel%2Fcore'.

```text
- @babel/core becomes %40babel%2Fcore
- Example URL: /v3/systems/npm/packages/%40babel%2Fcore
```

--------------------------------

### GetVersionBatch Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve multiple package versions via the v3alpha gRPC service using grpcurl. Supports batching up to 5000 requests.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetVersionBatch \ 
  -d '{"versionKeys": [{"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}, {"packageKey": {"system": "NPM", "name": "lodash"}, "version": "4.17.21"}]}'
```

--------------------------------

### npm Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example JSON object detailing npm package requirements, including dependencies, dev dependencies, peer dependencies, and operating system/CPU compatibility.

```json
{
  "npm": {
    "dependencies": {
      "dependencies": [
        {
          "name": "react-dom",
          "requirement": "^18.0.0"
        }
      ],
      "dev_dependencies": [
        {
          "name": "typescript",
          "requirement": "^4.0.0"
        }
      ],
      "peer_dependencies": [
        {
          "name": "react",
          "requirement": ">=16.8"
        }
      ]
    },
    "os": ["linux", "darwin"],
    "cpu": ["x64", "arm64"]
  }
}
```

--------------------------------

### Rust (Cargo) Dependencies Schema Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/requirements-schema.md

Example JSON structure for defining Rust crate dependencies, including dependency kind, features, and optionality.

```json
{
  "cargo": {
    "dependencies": [
      {
        "name": "serde",
        "requirement": "1.0",
        "kind": "normal",
        "optional": false,
        "uses_default_features": true,
        "features": ["derive"]
      },
      {
        "name": "tokio",
        "requirement": "1",
        "kind": "normal",
        "optional": true,
        "uses_default_features": true,
        "features": ["full"]
      },
      {
        "name": "criterion",
        "requirement": "0.4",
        "kind": "dev"
      }
    ],
    "features": [
      {
        "name": "default",
        "implies": ["std", "derive"]
      },
      {
        "name": "full",
        "implies": ["async", "network", "security"]
      }
    ]
  }
}
```

--------------------------------

### GetProject Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve information about a project using the v3 HTTP API. Requires URL encoding for project identifiers.

```curl
curl "https://api.deps.dev/v3/project/github/facebook/react"
```

--------------------------------

### GetPackage Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to retrieve package information using the v3 HTTP API. Requires URL encoding for package identifiers.

```curl
curl "https://api.deps.dev/v3/package/npm/react"
```

--------------------------------

### GetVersion Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to fetch specific version information for a package using the v3 HTTP API. Ensure correct URL encoding.

```curl
curl "https://api.deps.dev/v3/version/npm/react@17.0.2"
```

--------------------------------

### GetAdvisory Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates how to retrieve security advisory information for a package version using the v3 HTTP API. URL encoding is required.

```curl
curl "https://api.deps.dev/v3/advisory/npm/react@17.0.2"
```

--------------------------------

### npm Package Key Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example of a package key for the npm package management system. Used to uniquely identify an npm package, including scoped packages.

```json
{
  "system": "NPM",
  "name": "@babel/core"
}
```

--------------------------------

### Go Requirements Structure Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/requirements-schema.md

Demonstrates the JSON representation for Go module dependencies, including direct, indirect, replaces, and excludes directives.

```json
{
  "go": {
    "direct_dependencies": [
      {"name": "github.com/sirupsen/logrus", "requirement": "v1.9.0"},
      {"name": "github.com/spf13/cobra", "requirement": "v1.6.0"}
    ],
    "indirect_dependencies": [
      {"name": "golang.org/x/sys", "requirement": "v0.3.0"}
    ],
    "replaces": [
      {
        "src": {"name": "github.com/old/module", "requirement": ""},
        "replacement": {"name": "github.com/new/module", "requirement": "v1.0.0"}
      },
      {
        "src": {"name": "github.com/local/module", "requirement": "v1.0.0"},
        "local_path": "../local/module"
      }
    ],
    "excludes": [
      {"name": "github.com/broken/version", "requirement": "v1.5.0"}
    ]
  }
}
```

--------------------------------

### GetProjectPackageVersions Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates retrieving all package versions associated with a project using the v3 HTTP API. Requires URL encoding.

```curl
curl "https://api.deps.dev/v3/project_package_versions/github/facebook/react"
```

--------------------------------

### GetFindings Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates fetching security findings for a specific package version using the v3alpha HTTP API. This provides detailed vulnerability information.

```curl
curl "https://api.deps.dev/v3alpha/findings/npm/react@17.0.2"
```

--------------------------------

### Example JSON Response Structure

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Illustrates the typical JSON structure for package and version information returned by the API.

```json
{
  "package_key": {
    "system": "NPM",
    "name": "react"
  },
  "versions": [
    {
      "version_key": {
        "system": "NPM",
        "name": "react",
        "version": "18.2.0"
      },
      "published_at": "2023-06-14T15:57:42Z",
      "is_default": true,
      "licenses": ["MIT"]
    }
  ]
}
```

--------------------------------

### Get Requirements

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Fetches system-specific dependency declarations for a given package version.

```APIDOC
## GET /v3/systems/{system}/packages/{package}/versions/{version}:requirements

### Description
Returns the system-specific dependency declarations for a particular package version.

### Method
GET

### Endpoint
/v3/systems/{system}/packages/{package}/versions/{version}:requirements

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., npm, pip).
- **package** (string) - Required - The name of the package.
- **version** (string) - Required - The specific version of the package.

### Request Example
```bash
curl 'https://api.deps.dev/v3/systems/npm/packages/react/versions/18.2.0:requirements'
```
```

--------------------------------

### GetProjectBatch Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching multiple projects concurrently using the v3alpha HTTP API. Batch size is limited to 5000 projects.

```curl
curl -X POST \ 
  -H "Content-Type: application/json" \ 
  -d '{"projectKeys": [{"host": "github.com", "name": "facebook/react"}, {"host": "github.com", "name": "lodash/lodash"}]}' \ 
  https://api.deps.dev/v3alpha/project_batch
```

--------------------------------

### Get Project Info

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Retrieves metadata, scorecard, and OSS-Fuzz information for a given project.

```APIDOC
## GET /v3/projects/{project_path}

### Description
Retrieves project metadata, including its scorecard and OSS-Fuzz information.

### Method
GET

### Endpoint
/v3/projects/{project_path}

### Parameters
#### Path Parameters
- **project_path** (string) - Required - The path to the project (e.g., github.com/facebook/react).

### Request Example
```bash
curl 'https://api.deps.dev/v3/projects/github.com/facebook/react'
```
```

--------------------------------

### GetDependents Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates retrieving packages that depend on a given package version via the v3alpha gRPC service using grpcurl.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetDependents \ 
  -d '{"versionKey": {"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}}'
```

--------------------------------

### QueryContainerImages Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates querying container images via the v3alpha gRPC service using grpcurl. Accepts a query string for searching.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/QueryContainerImages \ 
  -d '{"query": "ubuntu"}'
```

--------------------------------

### Connect to deps.dev API with Go (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Example of establishing a gRPC connection to the deps.dev API using Go and creating an Insights client.

```go
import "deps.dev/api/v3"

conn, _ := grpc.Dial("api.deps.dev:443", grpc.WithTransportCredentials(creds))
client := v3.NewInsightsClient(conn)
resp, _ := client.GetPackage(ctx, &v3.GetPackageRequest{
  PackageKey: &v3.PackageKey{
    System: v3.System_NPM,
    Name: "react",
  },
})
```

--------------------------------

### GetDependencies Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates how to retrieve the dependencies of a specific package version via the v3 HTTP API. Requires URL encoding.

```curl
curl "https://api.deps.dev/v3/dependencies/npm/react@17.0.2"
```

--------------------------------

### Maven Dependency Structure Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/requirements-schema.md

Illustrates the JSON structure for Maven dependencies, including parent, dependencies, dependency management, and properties.

```json
{
  "maven": {
    "parent": {
      "system": "MAVEN",
      "name": "org.springframework.boot:spring-boot-starter-parent",
      "version": "2.7.0"
    },
    "dependencies": [
      {
        "name": "org.springframework.boot:spring-boot-starter-web",
        "version": "[2.7, 3.0)",
        "type": "jar",
        "scope": "compile",
        "optional": "false"
      },
      {
        "name": "junit:junit",
        "version": "4.13.2",
        "scope": "test",
        "optional": "false"
      }
    ],
    "dependency_management": [
      {
        "name": "org.springframework.cloud:spring-cloud-dependencies",
        "version": "2021.0.3",
        "type": "pom",
        "scope": "import",
        "origin": "management"
      }
    ],
    "properties": [
      {"name": "maven.compiler.source", "value": "11"},
      {"name": "maven.compiler.target", "value": "11"}
    ]
  }
}
```

--------------------------------

### Get Project Info (v3)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves information about a project hosted on platforms like GitHub, GitLab, or Bitbucket.

```APIDOC
## GET /v3/projects/{project_id}

### Description
Get project info

### Method
GET

### Endpoint
/v3/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier for the project.

### Response
#### Success Response (200)
- Information about the specified project.
```

--------------------------------

### PurlLookupBatch Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates looking up multiple packages by PURL simultaneously using the v3alpha HTTP API. Batch size is limited to 5000 PURLs.

```curl
curl -X POST \ 
  -H "Content-Type: application/json" \ 
  -d '{"purls": ["pkg:npm/react@17.0.2", "pkg:npm/lodash@4.17.21"]}' \ 
  https://api.deps.dev/v3alpha/purl_lookup_batch
```

--------------------------------

### GetDependents Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching packages that depend on a specific package version using the v3alpha HTTP API. Useful for impact analysis.

```curl
curl "https://api.deps.dev/v3alpha/dependents/npm/react@17.0.2"
```

--------------------------------

### POST Request Example for Batch Operations

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Use POST requests for batch endpoints, sending a JSON request body with an array of requests.

```bash
curl -X POST 'https://api.deps.dev/v3alpha/versionbatch' \
  -H 'Content-Type: application/json' \
  -d '{
    "requests": [
      {
        "version_key": {
          "system": "NPM",
          "name": "react",
          "version": "18.2.0"
        }
      }
    ]
  }'
```

--------------------------------

### HTTP REST API Usage

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

A practical guide to using the HTTP REST API, covering URL encoding, response formats, common usage patterns with curl examples, and error handling.

```APIDOC
## HTTP REST API Usage

### Description
This guide provides practical instructions for interacting with the deps.dev HTTP REST API. It covers essential aspects like URL encoding, understanding response formats, common usage patterns with examples (including cURL), and effective error handling.

### Key Topics
- URL encoding rules
- Response format documentation
- Common usage patterns with curl examples
- Error responses and handling
- HTTP headers and rate limiting
- Caching best practices
- Examples in Python, JavaScript/Node.js, Go, and cURL
```

--------------------------------

### PurlLookup Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to perform a PURL lookup via the v3alpha gRPC service using grpcurl. This method accepts a PURL string.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/PurlLookup \ 
  -d '{"purl": "pkg:npm/react@17.0.2"}'
```

--------------------------------

### Set Request Timeout with Context

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

This example shows how to set a timeout for a gRPC request using `context.WithTimeout`. It's crucial for preventing requests from hanging indefinitely.

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

resp, err := client.GetVersion(ctx, req)
```

--------------------------------

### GetPackage HTTP Request

Source: https://github.com/google/deps.dev/blob/main/_autodocs/api-v3-service.md

Use this snippet to retrieve comprehensive information about a package, including all its available versions, via an HTTP GET request.

```bash
curl 'https://api.deps.dev/v3/systems/npm/packages/react'
```

--------------------------------

### QueryContainerImages Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to query for container images using the v3alpha HTTP API. This endpoint allows searching for images based on various criteria.

```curl
curl "https://api.deps.dev/v3alpha/query_container_images?q=ubuntu"
```

--------------------------------

### GetFindingsBatch Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Demonstrates fetching security findings for multiple package versions via the v3alpha gRPC service using grpcurl. Supports batching up to 5000 requests.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/GetFindingsBatch \ 
  -d '{"versionKeys": [{"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}, {"packageKey": {"system": "NPM", "name": "lodash"}, "version": "4.17.21"}]}'
```

--------------------------------

### RubyGems Requirements Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/package-systems.md

Example JSON object representing RubyGems requirements, including runtime and development dependencies, and Ruby version constraints.

```json
{
  "rubygems": {
    "runtime_dependencies": [
      {
        "name": "activerecord",
        "requirement": "= 6.1.0"
      }
    ],
    "dev_dependencies": [
      {
        "name": "sqlite3",
        "requirement": ">= 0"
      }
    ],
    "required_ruby_version": ">= 2.5.0"
  }
}
```

--------------------------------

### Query Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to query for packages based on various criteria using the v3 HTTP API. Supports filtering by system, name, and version.

```curl
curl "https://api.deps.dev/v3/query?systems=npm&q=react"
```

--------------------------------

### Ruby (RubyGems) Requirements Schema Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/requirements-schema.md

Example JSON structure for defining Ruby gem dependencies, including runtime and development dependencies, and Ruby version requirements.

```json
{
  "rubygems": {
    "runtime_dependencies": [
      {"name": "rails", "requirement": ">= 6.0.0"},
      {"name": "pg", "requirement": ">= 1.1"}
    ],
    "dev_dependencies": [
      {"name": "rspec", "requirement": "~> 3.11"},
      {"name": "rubocop", "requirement": ">= 1.0"}
    ],
    "platform": "ruby",
    "required_ruby_version": ">= 2.7.0",
    "required_rubygems_version": ">= 2.7.0"
  }
}
```

--------------------------------

### Go Client: GetVersion Request

Source: https://github.com/google/deps.dev/blob/main/_autodocs/grpc-api-usage.md

Example of making a GetVersion request using the Go client. This snippet shows how to specify the version key and process the response, including licenses, publication date, and advisories.

```go
ctx := context.Background()
resp, err := client.GetVersion(ctx, &depsdev.GetVersionRequest{
  VersionKey: &depsdev.VersionKey{
    System:  depsdev.System_NPM,
    Name:    "react",
    Version: "18.2.0",
  },
})

if err != nil {
  log.Fatal(err)
}

fmt.Printf("Licenses: %v\n", resp.Licenses)
fmt.Printf("Published: %v\n", resp.PublishedAt)

for _, advisory := range resp.AdvisoryKeys {
  fmt.Printf("Advisory: %s\n", advisory.Id)
}
```

--------------------------------

### Get npm package information

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves general information about an npm package.

```APIDOC
## GET /v3/systems/npm/packages/{packageName}

### Description
Retrieves information for a specified npm package.

### Method
GET

### Endpoint
/v3/systems/npm/packages/{packageName}

### Parameters
#### Path Parameters
- **packageName** (string) - Required - The name of the npm package.

### Response
#### Success Response (200)
- **package_key** (object) - The canonicalized package identifier.
- **versions** (array) - A list of available versions for the package.
```

--------------------------------

### GetFindingsBatch Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Shows how to retrieve security findings for multiple package versions in a single request using the v3alpha HTTP API. Limited to 5000 requests.

```curl
curl -X POST \ 
  -H "Content-Type: application/json" \ 
  -d '{"versionKeys": [{"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}, {"packageKey": {"system": "NPM", "name": "lodash"}, "version": "4.17.21"}]}' \ 
  https://api.deps.dev/v3alpha/findings_batch
```

--------------------------------

### Get Requirements (v3)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves the system-specific requirements for a given package version.

```APIDOC
## GET /v3/systems/{system}/packages/{name}/versions/{version}:requirements

### Description
Get requirements

### Method
GET

### Endpoint
/v3/systems/{system}/packages/{name}/versions/{version}:requirements

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., GO, NPM, PYPI).
- **name** (string) - Required - The name of the package.
- **version** (string) - Required - The specific version of the package.

### Response
#### Success Response (200)
- System-specific requirement schemas for the package version.
```

--------------------------------

### GetVersionBatch Example (HTTP)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates fetching multiple package versions simultaneously using the v3alpha HTTP API. Batch requests are limited to 5000 items.

```curl
curl -X POST \ 
  -H "Content-Type: application/json" \ 
  -d '{"versionKeys": [{"packageKey": {"system": "NPM", "name": "react"}, "version": "17.0.2"}, {"packageKey": {"system": "NPM", "name": "lodash"}, "version": "4.17.21"}]}' \ 
  https://api.deps.dev/v3alpha/version_batch
```

--------------------------------

### Get Findings (v3alpha)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Retrieves security findings, warnings, and recommendations for a specific package.

```APIDOC
## GET /v3alpha/systems/{system}/packages/{package}:findings

### Description
Returns security findings, warnings, and recommendations for a given package.

### Method
GET

### Endpoint
/v3alpha/systems/{system}/packages/{package}:findings

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., npm, pip).
- **package** (string) - Required - The name of the package.

### Request Example
```bash
curl 'https://api.deps.dev/v3alpha/systems/npm/packages/lodash:findings'
```
```

--------------------------------

### Get version with scoped package

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves information for a specific version of a scoped npm package.

```APIDOC
## GET /v3/systems/npm/packages/{scopedPackageName}/versions/{version}

### Description
Retrieves information for a specific version of a scoped npm package. The package name must be URL-encoded.

### Method
GET

### Endpoint
/v3/systems/npm/packages/{scopedPackageName}/versions/{version}

### Parameters
#### Path Parameters
- **scopedPackageName** (string) - Required - The URL-encoded name of the scoped npm package (e.g., %40babel%2Fcore).
- **version** (string) - Required - The specific version string of the package.

### Response
#### Success Response (200)
- **package_key** (object) - The canonicalized package identifier.
- **versions** (array) - A list containing the specified version of the package.
```

--------------------------------

### Get Dependent Counts (v3alpha)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves the count of dependent packages for a specific version of a package.

```APIDOC
## GET /v3alpha/systems/{system}/packages/{name}/versions/{version}:dependents

### Description
Get dependent counts

### Method
GET

### Endpoint
/v3alpha/systems/{system}/packages/{name}/versions/{version}:dependents

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., GO, NPM, PYPI).
- **name** (string) - Required - The name of the package.
- **version** (string) - Required - The specific version of the package.

### Response
#### Success Response (200)
- The number of packages that depend on the specified package version.
```

--------------------------------

### Get Security Advisory (v3)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves details about a specific security advisory using its ID.

```APIDOC
## GET /v3/advisories/{advisory_id}

### Description
Get security advisory

### Method
GET

### Endpoint
/v3/advisories/{advisory_id}

### Parameters
#### Path Parameters
- **advisory_id** (string) - Required - The unique identifier for the security advisory.

### Response
#### Success Response (200)
- Details of the security advisory.
```

--------------------------------

### PurlLookupBatch Example (gRPC)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/MANIFEST.txt

Illustrates fetching multiple package details via PURLs using the v3alpha gRPC service with grpcurl. Supports batching up to 5000 PURLs.

```bash
grpcurl -plaintext localhost:8080 \ 
  deps.v3alpha.Service/PurlLookupBatch \ 
  -d '{"purls": ["pkg:npm/react@17.0.2", "pkg:npm/lodash@4.17.21"]}'
```

--------------------------------

### Base64 Encoded Bytes Value Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Bytes fields, such as hashes, are base64-encoded within JSON responses.

```json
{
  "hash": {
    "type": "SHA256",
    "value": "aGVsbG8gd29ybGQ="
  }
}
```

--------------------------------

### JSON Response Structure Example

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

All API responses are in JSON format, with nested objects and arrays as needed.

```json
{
  "field1": "value",
  "field2": {
    "nested": "value"
  },
  "array": [
    {"item": 1},
    {"item": 2}
  ]
}
```

--------------------------------

### Get Dependencies

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Retrieves the resolved dependency graph for a specific package version, including nodes and edges.

```APIDOC
## GET /v3/systems/{system}/packages/{package}/versions/{version}:dependencies

### Description
Returns the resolved dependency graph for a specific package version, presented as a set of nodes and edges.

### Method
GET

### Endpoint
/v3/systems/{system}/packages/{package}/versions/{version}:dependencies

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., npm, pip).
- **package** (string) - Required - The name of the package.
- **version** (string) - Required - The specific version of the package.

### Request Example
```bash
curl 'https://api.deps.dev/v3/systems/npm/packages/react/versions/18.2.0:dependencies'
```
```

--------------------------------

### Get Security Findings (v3alpha)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves security findings for a specific package within a given system.

```APIDOC
## GET /v3alpha/systems/{system}/packages/{name}:findings

### Description
Get security findings

### Method
GET

### Endpoint
/v3alpha/systems/{system}/packages/{name}:findings

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., GO, NPM, PYPI).
- **name** (string) - Required - The name of the package.

### Response
#### Success Response (200)
- Security findings related to the specified package.
```

--------------------------------

### Get Findings (v3alpha)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Retrieve security findings, warnings, and recommendations for a package using the v3alpha endpoint.

```bash
curl 'https://api.deps.dev/v3alpha/systems/npm/packages/lodash:findings'
```

--------------------------------

### Get Dependency Graph (v3)

Source: https://github.com/google/deps.dev/blob/main/_autodocs/README.md

Retrieves the dependency graph for a specific version of a package, showing its resolved dependencies.

```APIDOC
## GET /v3/systems/{system}/packages/{name}/versions/{version}:dependencies

### Description
Get dependency graph

### Method
GET

### Endpoint
/v3/systems/{system}/packages/{name}/versions/{version}:dependencies

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., GO, NPM, PYPI).
- **name** (string) - Required - The name of the package.
- **version** (string) - Required - The specific version of the package.

### Response
#### Success Response (200)
- The resolved dependency graph for the specified package version.
```

--------------------------------

### Get Package Information

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Retrieves comprehensive information about a specific package, including all its versions, publication dates, and metadata.

```APIDOC
## GET /v3/systems/{system}/packages/{package}

### Description
Retrieves all versions, publication dates, and metadata for a given package within a specified system.

### Method
GET

### Endpoint
/v3/systems/{system}/packages/{package}

### Parameters
#### Path Parameters
- **system** (string) - Required - The package management system (e.g., npm, pip).
- **package** (string) - Required - The name of the package.

### Request Example
```bash
curl 'https://api.deps.dev/v3/systems/npm/packages/react'
```
```

--------------------------------

### Query by Version Key

Source: https://github.com/google/deps.dev/blob/main/_autodocs/http-api-usage.md

Specify package version details using `version_key.system`, `version_key.name`, and `version_key.version` query parameters.

```text
?version_key.system=npm&version_key.name=react&version_key.version=18.2.0
```