Implement admin APIs (#117)

## Problem
We need the admin APIs from `2025-04` implemented in Go to support both
the CLI and Terraform.

## Solution
Implement new `AdminClient` which encapsulates all of the network
operations for working with the admin API. This is a separate client
from the generic `Client`, and has it's own `NewAdminClientParams`
configuration struct. Additionally, there are two new functions for
authenticating and generating a new `AdminClient` pointer:
`NewAdminClient` and `NewAdminClientWithContext`.

The operations are broken across three interfaces:

- `ProjectClient`
- `OrganizationClient`
- `APIKeyClient`

Each of these has the relevant crud operations for the resources, so you
call them like `adminClient.Project.List()`, or
`adminClient.APIKey.List()`.

New files:
- `admin_client.go`
- `admin_client_test.go`

Added a new `AdminIntegrationTests` suite to wrap all of the integration
tests associated with the admin API. There's full end-to-end tests for
all crud operations except `DeleteOrganization` in the
`ademin_client_test.go` file.

Example usage:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/pinecone-io/go-pinecone/v4/pinecone"
)

func main() {
	ctx := context.Background()

	// Create an AdminClient using your credentials
	adminClient, err := pinecone.NewAdminClient(pinecone.NewAdminClientParams{
		ClientId:     "YOUR_CLIENT_ID",
		ClientSecret: "YOUR_CLIENT_SECRET",
	})
	if err != nil {
		log.Fatalf("failed to create AdminClient: %v", err)
	}

	// Create a new project
	project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{
		Name: "example-project",
	})
	if err != nil {
		log.Fatalf("failed to create project: %v", err)
	}
	fmt.Printf("Created project: %s\n", project.Name)

	// Create a new API within that project
	apiKey, err := adminClient.APIKey.Create(ctx, project.Id, &pinecone.CreateAPIKeyParams{
		Name: "example-api-key",
	})
	if err != nil {
		log.Fatalf("failed to create API key: %v", err)
	}
	fmt.Printf("Created API key: %s\n", apiKey.Id)

	// List all projects
	projects, err := adminClient.Project.List(ctx)
	if err != nil {
		log.Fatalf("failed to list projects: %v", err)
	}
	fmt.Printf("You have %d project(s)\n", len(projects))

	// List API keys for the created project
	apiKeys, err := adminClient.APIKey.List(ctx, project.Id)
	if err != nil {
		log.Fatalf("failed to list API keys: %v", err)
	}
	fmt.Printf("Project '%s' has %d API key(s)\n", project.Name, len(apiKeys))
}
```

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [X] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update
- [ ] Infrastructure change (CI configs, etc)
- [ ] Non-code change (docs, etc)
- [ ] None of the above: (explain here)

## Test Plan
New integration tests for `AdminClient` and all operations added for CI.
You can pull this branch down locally and test against the built client
locally.

Author: austin-denoble

.github/workflows/ci.yaml

@@ -29,14 +29,16 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.21.x"
+          go-version: '1.21.x'
       - name: Install dependencies
         run: |
           go get ./pinecone
       - name: Run tests
         run: go test -count=1 -v ./pinecone
         env:
           PINECONE_API_KEY: ${{ secrets.API_KEY }}
+          PINECONE_CLIENT_ID: ${{ secrets.CLIENT_ID }}
+          PINECONE_CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }}
       - name: Run local integration tests
         run: go test -count=1 -v ./pinecone -run TestRunLocalIntegrationSuite -tags=localServer
         env:

README.md

@@ -13,9 +13,10 @@ visit https://pkg.go.dev/github.com/pinecone-io/go-pinecone/v4/pinecone.
 
 go-pinecone contains
 
-- gRPC bindings for [Data Plane](https://docs.pinecone.io/reference/api/2024-07/data-plane) operations
-- REST bindings for [Control Plane](https://docs.pinecone.io/reference/api/2024-07/control-plane)
+- gRPC bindings for [Data Plane](https://docs.pinecone.io/reference/api/2025-04/data-plane) operations
+- REST bindings for [Control Plane](https://docs.pinecone.io/reference/api/2025-04/control-plane)
   operations
+- REST bindings for [Admin API](https://docs.pinecone.io/reference/api/2025-04/admin/)
 
 See the [Pinecone API Docs](https://docs.pinecone.io/reference/) for more information.
 
@@ -43,12 +44,12 @@ For more information on setting up a Go project, see the [Go documentation](http
 
 ## Usage
 
-### Initializing the client
+### Initializing a Client
 
 **Authenticating via an API key**
 
-When initializing the client with a Pinecone API key, you must construct a `NewClientParams` object and pass it to the
-`NewClient` function.
+When initializing a `Client` with a Pinecone API key, you must construct a `NewClientParams` object and pass it to the
+`NewClient` function which returns `Client`.
 
 It's recommended that you set your Pinecone API key as an environment variable (`"PINECONE_API_KEY"`) and access it that
 way. Alternatively, you can pass it in your code directly.
@@ -113,6 +114,75 @@ func main() {
 }
 ```
 
+### Initializing an AdminClient (Admin API)
+
+When initializing an `AdminClient` you must construct a `NewAdminClientParams` object and pass it to the
+`NewAdminClient` or `NewAdminClientWithContext` functions which return `AdminClient`.
+
+`AdminClient` is a struct used for accessing the Pinecone Admin API. A prerequisite for using this class is to have a [service account](https://docs.pinecone.io/guides/organizations/manage-service-accounts). To create a service
+account, visit the [Pinecone web console](https://app.pinecone.io) and navigate to the `Access > Service Accounts` section.
+
+**Authenticating via client ID and secret**
+
+After creating a service account, you will be provided with a client ID and secret. These values can be passed via the `NewAdminClientParams` struct, or by setting the `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` environment variables. The `NewAdminClient` function handles the authentication handshake, and returns an authenticated `AdminClient`.
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/pinecone-io/go-pinecone/v4/pinecone"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Create an AdminClient using your credentials
+	adminClient, err := pinecone.NewAdminClient(pinecone.NewAdminClientParams{
+		ClientId:     "YOUR_CLIENT_ID",
+		ClientSecret: "YOUR_CLIENT_SECRET",
+	})
+	if err != nil {
+		log.Fatalf("failed to create AdminClient: %v", err)
+	}
+
+	// Create a new project
+	project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{
+		Name: "example-project",
+	})
+	if err != nil {
+		log.Fatalf("failed to create project: %v", err)
+	}
+	fmt.Printf("Created project: %s\n", project.Name)
+
+	// Create a new API within that project
+	apiKey, err := adminClient.APIKey.Create(ctx, project.Id, &pinecone.CreateAPIKeyParams{
+		Name: "example-api-key",
+	})
+	if err != nil {
+		log.Fatalf("failed to create API key: %v", err)
+	}
+	fmt.Printf("Created API key: %s\n", apiKey.Id)
+
+	// List all projects
+	projects, err := adminClient.Project.List(ctx)
+	if err != nil {
+		log.Fatalf("failed to list projects: %v", err)
+	}
+	fmt.Printf("You have %d project(s)\n", len(projects))
+
+	// List API keys for the created project
+	apiKeys, err := adminClient.APIKey.List(ctx, project.Id)
+	if err != nil {
+		log.Fatalf("failed to list API keys: %v", err)
+	}
+	fmt.Printf("Project '%s' has %d API key(s)\n", project.Name, len(apiKeys))
+}
+```
+
 ## Indexes
 
 ### Create indexes

codegen/apis

@@ -6,13 +6,15 @@ version=$1 # e.g. 2024-07
 db_control_module="db_control"
 db_data_module="db_data"
 inference_module="inference"
+admin_module="admin"
 
 # generated grpc output destination paths
 # db_data_destination must align with the option go_package in the proto file: 
 # https://github.com/pinecone-io/apis/blob/d1d005e75cc9fe9a5c486ef9218fe87b57765961/src/release/db/data/data.proto#L3
 db_data_destination="internal/gen/${db_data_module}"
 db_control_destination="internal/gen/${db_control_module}"
 inference_destination="internal/gen/${inference_module}"
+admin_destination="internal/gen/${admin_module}"
 
 # version file
 version_file="internal/gen/api_version.go"
@@ -22,6 +24,7 @@ db_data_rest_destination="${db_data_destination}/rest"
 db_data_oas_file="${db_data_rest_destination}/${db_data_module}_${version}.oas.go"
 db_control_oas_file="${db_control_destination}/${db_control_module}_${version}.oas.go"
 inference_oas_file="${inference_destination}/${inference_module}_${version}.oas.go"
+admin_oas_file="${admin_destination}/${admin_module}_${version}.oas.go"
 
 set -eux -o pipefail
 
@@ -109,6 +112,11 @@ rm -rf "${inference_destination}"
 mkdir -p "${inference_destination}"
 generate_oas_client $inference_module $inference_oas_file
 
+# Generate admin oas client
+rm -rf "${admin_destination}"
+mkdir -p "${admin_destination}"
+generate_oas_client $admin_module $admin_oas_file
+
 # Generate db_data oas and proto clients
 rm -rf "${db_data_destination}"
 mkdir -p "${db_data_destination}"