docs: update docs

apis/doc.go

@@ -1,46 +1,78 @@
 // Package apis provides multiple APIs to interact with the Apicurio Registry.
 //
-// The apis package exposes different high-level APIs to manage resources in the Apicurio Registry,
-// such as artifacts, metadata, and administrative operations. Each API abstracts specific
-// functionality of the Apicurio Registry, providing a clean and easy-to-use interface.
+// The apis package exposes high-level APIs to manage resources in the Apicurio Registry,
+// such as artifacts, versions, metadata, and administrative operations. Each API
+// encapsulates specific functionalities of the Apicurio Registry, ensuring a modular and
+// user-friendly interface.
 //
 // Available APIs:
-//   - AdminAPI: Provides administrative operations, such as clearing the cache and managing system-level settings.
-//   - ArtifactsAPI: Manages artifact lifecycles, including creation, retrieval, versioning, and deletion of schemas.
-//   - MetadataAPI: Handles schema metadata operations, such as tagging, labeling, and descriptions.
-//   - RulesAPI: Allows configuration and management of rules for compatibility and validation.
-//   - BranchesAPI: Allows configuration and management of branches for artifact versioning.
-//   - GroupsAPI: Manages groups related resource in apicurio registry.
-//   - VersionsAPI: Manages versions related resource in apicurio registry.
-//   - SystemsAPI: Manages systems related resource in apicurio registry.
-//   - ...
-//
-// Features:
-//   - Register, retrieve, and delete artifacts.
-//   - Perform schema versioning and compatibility checks.
-//   - Manage metadata, tags, and labels for artifacts.
-//   - Execute administrative actions on the Apicurio Registry.
-//
-// Example usage:
-//
-//	import "github.com/mollie/go-apicurio-registry/apis"
+//
+//  1. **ArtifactsAPI**: Manages artifacts (schemas), including creation, retrieval,
+//     updating, and deletion.
+//
+//  2. **VersionsAPI**: Handles operations related to artifact versions, such as retrieving
+//     and managing version history.
+//
+//  3. **GroupsAPI**: Supports grouping of artifacts to enable multi-tenancy and
+//     organizational categorization.
+//
+//  4. **MetadataAPI**: Provides methods to manage artifact metadata and perform
+//     compatibility checks.
+//
+//  5. **AdminAPI**: Enables administrative operations like clearing caches, monitoring
+//     system health, and managing global settings.
+//
+// 6. **SystemAPI**: Offers methods for querying registry status and configuration.
+//
+// Example Usage:
+//
+// The following example demonstrates how to use the ArtifactsAPI to create and retrieve an artifact:
+//
+//	package main
+//
+//	import (
+//		"fmt"
+//		"github.com/mollie/go-apicurio-registry/apis"
+//		"github.com/mollie/go-apicurio-registry/client"
+//		"github.com/mollie/go-apicurio-registry/models"
+//	)
 //
 //	func main() {
-//	    // Initialize the Artifacts API
-//	    artifactsAPI := apis.NewArtifactsAPI("https://registry.example.com")
-//
-//	    // Register a new artifact
-//	    err := artifactsAPI.RegisterArtifact("example-subject", `{"type":"record","name":"example"}`)
-//	    if err != nil {
-//	        log.Fatal("Error registering artifact:", err)
-//	    }
-//	    fmt.Println("Artifact registered successfully")
-//
-//	    // Retrieve an Artifact
-//	    artifact, err := artifactsAPI.GetArtifact("example-subject", "latest")
-//	    if err != nil {
-//	        log.Fatal("Error fetching artifact:", err)
-//	    }
-//	    fmt.Println("Retrieved artifact:", artifact)
+//		// Initialize the API client
+//		config := client.Config{
+//			BaseURL: "https://my-registry.example.com",
+//			AuthToken: "my-token",
+//		}
+//		apiClient := client.NewApicurioClient(config)
+//
+//		// Access the ArtifactsAPI
+//		artifactsAPI := apis.NewArtifactsAPI(apiClient)
+//
+//		// Create a new artifact
+//		artifact := models.Artifact{
+//			GroupID: "example-group",
+//			ID: "example-artifact",
+//			Content: []byte(`{"type": "record", "name": "Example", "fields": [{"name": "field1", "type": "string"}]}`),
+//			ContentType: "application/json",
+//		}
+//		response, err := artifactsAPI.Create(artifact)
+//		if err != nil {
+//			fmt.Printf("Error creating artifact: %v\n", err)
+//			return
+//		}
+//		fmt.Printf("Artifact created with ID: %s\n", response.ID)
+//
+//		// Retrieve artifact metadata
+//		metadata, err := artifactsAPI.GetMetadata("example-group", "example-artifact")
+//		if err != nil {
+//			fmt.Printf("Error retrieving metadata: %v\n", err)
+//			return
+//		}
+//		fmt.Printf("Artifact metadata: %+v\n", metadata)
 //	}
+//
+// Note:
+//
+// Each API can be accessed via its respective constructor function (e.g., `NewArtifactsAPI`,
+// `NewAdminAPI`). These APIs are designed to integrate seamlessly with the client package.
 package apis

client/doc.go

@@ -1,7 +1,63 @@
-// Package client provides the core functionality to interact with
-// the Apicurio Registry. It includes methods to retrieve, register,
-// and validate schemas.
+// Package client provides the core client implementation for interacting with the Apicurio Registry.
 //
-// This package is the backbone of the library, and developers
-// typically start with the `NewApicurioClient` function.
+// The client package is the entry point for initializing and configuring the Apicurio Registry client.
+// It abstracts the complexities of making HTTP requests to the registry and provides a clean interface
+// for developers to use in their applications.
+//
+// Features:
+//
+// - Centralized configuration for base URL and authentication.
+// - Automatic retry mechanisms for transient failures.
+// - Thread-safe implementation suitable for concurrent use.
+// - Extensible architecture to support additional features and middleware.
+//
+// Usage:
+//
+// To use the client, create a new instance using the `NewApicurioClient` function and pass a `Config` structure
+// with the required settings such as BaseURL and AuthToken.
+//
+// Example:
+//
+//	package main
+//
+//	import (
+//		"fmt"
+//		"github.com/mollie/go-apicurio-registry/client"
+//	)
+//
+//	func main() {
+//		// Define the client configuration
+//		config := client.Config{
+//			BaseURL: "https://my-registry.example.com",
+//			AuthToken: "my-token",
+//		}
+//
+//		// Initialize the client
+//		apiClient := client.NewApicurioClient(config)
+//
+//		// Check the connection to the registry
+//		status, err := apiClient.CheckConnection()
+//		if err != nil {
+//			fmt.Printf("Error connecting to the registry: %v\n", err)
+//			return
+//		}
+//		fmt.Printf("Registry status: %v\n", status)
+//	}
+//
+// Configuration:
+//
+// The `Config` struct contains the following fields:
+// - BaseURL: The URL of the Apicurio Registry.
+// - AuthToken: A token used for authenticating requests.
+// - HTTPClient: (Optional) A custom HTTP client for advanced use cases.
+//
+// Methods:
+//
+// The client provides several methods to interact with the registry, including:
+// - `CheckConnection`: Verifies if the registry is reachable.
+// - `DoRequest`: Executes raw HTTP requests for advanced use cases.
+//
+// Thread Safety:
+//
+// The client is designed to be thread-safe and can be used in concurrent environments without additional synchronization.
 package client

doc.go

@@ -1,21 +1,68 @@
-// Package apicurio provides a client library for interacting with the Apicurio Registry.
-// It allows developers to manage schemas, validate payloads, and perform schema evolution.
+// Package apicurio provides a Go client library for interacting with the Apicurio Registry.
+//
+// The library enables developers to seamlessly integrate with the Apicurio Registry
+// for managing, evolving, and validating schemas in a variety of serialization formats.
 //
 // Features:
-// - CRUD operations on schemas.
-// - Schema validation and compatibility checks.
-// - Support for multiple serialization formats like Avro, Protobuf, and JSON Schema.
 //
-// Example usage:
+// - CRUD operations on schemas (artifacts) including creation, retrieval, update, and deletion.
+// - Management of schema versions, branches, and metadata.
+// - Group-based organization for schemas to support multi-tenancy.
+// - Schema validation and compatibility checks for supported formats such as Avro, Protobuf, and JSON Schema.
+// - System-level operations such as retrieving registry status and configuration.
+//
+// Structure:
+//
+// The library is structured into the following key components:
+//
+//  1. **Client**: Provides an entry point for interacting with the registry.
+//     Use the `client.NewApicurioClient` function to create a new client instance.
+//
+//  2. **APIs**: Contains modular functions for specific operations such as managing artifacts,
+//     branches, versions, groups, and performing administrative tasks.
+//
+// 3. **Models**: Defines data structures for requests, responses, and errors used across the library.
 //
-//	import "github.com/mollie/go-apicurio-registry/client"
+// Example Usage:
+//
+// The following example demonstrates how to create a new artifact and retrieve its metadata:
+//
+//	package main
+//
+//	import (
+//		"fmt"
+//		"github.com/mollie/go-apicurio-registry/client"
+//		"github.com/mollie/go-apicurio-registry/models"
+//	)
 //
 //	func main() {
-//	    client := client.NewApicurioClient("https://registry.example.com")
-//	    schema, err := client.GetSchema("example-subject", "latest")
-//	    if err != nil {
-//	        log.Fatal(err)
-//	    }
-//	    fmt.Println("Schema:", schema)
+//		// Initialize the client
+//		config := client.Config{
+//			BaseURL: "https://my-registry.example.com",
+//			AuthToken: "my-token",
+//		}
+//		apiClient := client.NewApicurioClient(config)
+//
+//		// Create a new artifact
+//		artifact := models.Artifact{
+//			GroupID: "example-group",
+//			ID: "example-artifact",
+//			Content: []byte(`{"type": "record", "name": "Example", "fields": [{"name": "field1", "type": "string"}]}`),
+//			ContentType: "application/json",
+//		}
+//		response, err := apiClient.Artifacts.Create(artifact)
+//		if err != nil {
+//			fmt.Printf("Error creating artifact: %v\n", err)
+//			return
+//		}
+//		fmt.Printf("Artifact created with ID: %s\n", response.ID)
+//
+//		// Retrieve artifact metadata
+//		metadata, err := apiClient.Artifacts.GetMetadata("example-group", "example-artifact")
+//		if err != nil {
+//			fmt.Printf("Error retrieving metadata: %v\n", err)
+//			return
+//		}
+//		fmt.Printf("Artifact metadata: %+v\n", metadata)
 //	}
 package apicurio