apicurio

README

Go-APICURIO-SDK

Go-APICURIO-SDK is an open-source Go SDK for interacting with Apicurio Schema Registry v3.0 APIs. This library provides an idiomatic Go interface to manage schemas, validate data, and handle schema evolution in Go applications. It is designed to make it easy for developers to integrate the Apicurio Schema Registry into their Go-based microservices or event-driven systems.

🚧 Work In Progress

This SDK is currently under active development. Key features and improvements are being added incrementally. While contributions and feedback are welcome, please note that some APIs and features may change as the project evolves.

Features

• Schema Management: Create, update, delete, and retrieve schemas.
• Validation: Validate payloads against registered schemas.
• Schema Evolution: Tools for managing schema compatibility and evolution.
• Integration: Works seamlessly with the Apicurio Schema Registry.

Getting Started

Prerequisites

• Go 1.18+ installed on your system.
• Access to an Apicurio Schema Registry instance.

Installation

To use the SDK, add it to your project using go get:

go get github.com/mollie/go-apicurio-registry

Development

Running Locally with Docker This project includes a docker-compose.yml file for setting up a local Apicurio Schema Registry instance. Run the following command to start the registry:

docker-compose up

Running Tests

The repository includes unit and integration tests. Use the following command to run all tests:

go test ./...

Contribution Guidelines

Contributions are welcome! Please see the CONTRIBUTING.md (to be added) for details on the process.

License

This project is licensed under the Apache License 2.0.

Documentation

Overview

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 (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.

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() {
	// 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)
}