add Golang API docs

README.md

@@ -6,7 +6,6 @@
 
 <a href="https://kyverno.github.io/kyverno-json" rel="https://kyverno.github.io/kyverno-json">![logo](website/docs/static/kyverno-json-horizontal.png)</a>
 
-
 Use Kyverno's powerful, declarative, low-code policies to validate any runtime or configuration data that can be converted to JSON including:
 * Terraform files
 * Dockerfiles
@@ -15,6 +14,8 @@ Use Kyverno's powerful, declarative, low-code policies to validate any runtime o
 
 Run `kyverno-json` as a CLI, or a web application with a REST API. Or, integrate as a Golang library.
 
+**WARNING: ⚠️ Kyverno JSON is in early development and changes may not be backwards compatible.**
+
 ## 📙 Documentation
 
 Documentation is available at: https://kyverno.github.io/kyverno-json
@@ -33,23 +34,17 @@ We are here to help!
 
 👉 For discussions or questions, join the [Kyverno Slack channel](https://slack.k8s.io/#kyverno).
 
-👉 For community meeting access, join the [mailing list](https://groups.google.com/g/kyverno).
-
-👉 To get notified ⭐️ [star this repository](https://github.com/kyverno/kyverno-json/stargazers).
+👉 To get notified on updates ⭐️ [star this repository](https://github.com/kyverno/kyverno-json/stargazers).
 
 ## ➕ Contributing
 
 Thanks for your interest in contributing to Kyverno! Here are some steps to help get you started:
 
-✔ Read and agree to the [Contribution Guidelines](/CONTRIBUTING.md).
-
-✔ Check out the [good first issues](https://github.com/kyverno/kyverno-json/labels/good%20first%20issue) list. Add a comment with `/assign` to request assignment of the issue.
+✔ Look through the [good first issues](https://github.com/kyverno/kyverno-json/labels/good%20first%20issue) list. Add a comment with `/assign` to request assignment of the issue.
 
 ✔ Check out the Kyverno [Community page](https://kyverno.io/community/) for other ways to get involved.
 
-## Developer Documentation
-
-Developer documentation can be found in the [.docs](./.docs/) folder.
+✔ Read the developer documentation in the [.docs](./.docs/) folder.
 
 ## License
 

go.mod

@@ -18,6 +18,7 @@ require (
 	go.uber.org/multierr v1.11.0
 	golang.org/x/crypto v0.14.0
 	gopkg.in/inf.v0 v0.9.1
+	gopkg.in/yaml.v2 v2.4.0
 	gopkg.in/yaml.v3 v3.0.1
 	gotest.tools v2.2.0+incompatible
 	k8s.io/apimachinery v0.28.3
@@ -125,7 +126,6 @@ require (
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20231009173412-8bfb1ae86b6c // indirect
 	google.golang.org/grpc v1.59.0 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
-	gopkg.in/yaml.v2 v2.4.0 // indirect
 	k8s.io/api v0.28.3 // indirect
 	k8s.io/apiextensions-apiserver v0.28.1 // indirect
 	k8s.io/apiserver v0.28.3 // indirect

test/api/go/main/main.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+
+	jsonengine "github.com/kyverno/kyverno-json/pkg/json-engine"
+	"github.com/kyverno/kyverno-json/pkg/policy"
+)
+
+const policyYAML = `
+apiVersion: json.kyverno.io/v1alpha1
+kind: ValidatingPolicy
+metadata:
+  name: authz
+spec:
+  rules:
+  - name: delete-checks
+    match:
+      all:
+        (input.method): "DELETE"
+    assert:
+      all:
+      - check:
+          role: "admin"
+`
+
+func main() {
+	policies, err := policy.Parse([]byte(policyYAML))
+	if err != nil {
+		panic(err)
+	}
+
+	// load payloads
+	requestJSON := `{
+		"name": "Annie",
+		"role": "admin",
+		"input": {
+			"method": "DELETE",
+			"path":   "/red-files"
+		}
+	}`
+
+	var payload interface{}
+	if err := json.Unmarshal([]byte(requestJSON), &payload); err != nil {
+		panic(err)
+	}
+
+	// create a JsonEngineRequest
+	request := jsonengine.JsonEngineRequest{
+		Resources: []interface{}{payload},
+		Policies:  policies,
+	}
+
+	// create a J
+	engine := jsonengine.New()
+
+	responses := engine.Run(context.Background(), request)
+
+	logger := log.Default()
+	for _, resp := range responses {
+		if resp.Error != nil {
+			// ...handle execution error
+			logger.Printf("policy error: %v", resp.Error)
+		}
+
+		if resp.Failure != nil {
+			// ...handle policy failure
+			logger.Printf("policy failure: %v", resp.Failure)
+		}
+	}
+}

website/docs/go-library/index.md

@@ -1,4 +1,89 @@
 # Usage
 
+The Go API provides a way to embed the Kyverno JSON engine in Go programs that validate JSON payloads using Kyverno policies.
 
-tbd...
+The Go API can be added to a program's dependencies as follows:
+
+```sh
+go get github.com/kyverno/kyverno-json/pkg/jsonengine
+go get github.com/kyverno/kyverno-json/pkg/policy
+
+```
+
+Here is a sample program that shows the overall flow for programatically using the Kyverno JSON Engine:
+
+```go
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+
+	jsonengine "github.com/kyverno/kyverno-json/pkg/json-engine"
+	"github.com/kyverno/kyverno-json/pkg/policy"
+)
+
+const policyYAML = `
+apiVersion: json.kyverno.io/v1alpha1
+kind: ValidatingPolicy
+metadata:
+  name: authz
+spec:
+  rules:
+  - name: delete-checks
+    match:
+      all:
+        (input.method): "DELETE"
+    assert:
+      all:
+      - check:
+          role: "admin"
+`
+
+func main() {
+	policies, err := policy.Parse([]byte(policyYAML))
+	if err != nil {
+		panic(err)
+	}
+
+	// load payloads
+	requestJSON := `{
+		"name": "Annie",
+		"role": "admin",
+		"input": {
+			"method": "DELETE",
+			"path":   "/red-files"
+		}
+	}`
+
+	var payload interface{}
+	if err := json.Unmarshal([]byte(requestJSON), &payload); err != nil {
+		panic(err)
+	}
+
+	// create a JsonEngineRequest
+	request := jsonengine.JsonEngineRequest{
+		Resources: []interface{}{payload},
+		Policies:  policies,
+	}
+
+	// create a J
+	engine := jsonengine.New()
+
+	responses := engine.Run(context.Background(), request)
+
+	logger := log.Default()
+	for _, resp := range responses {
+		if resp.Error != nil {
+			// ...handle execution error
+			logger.Printf("policy error: %v", resp.Error)
+		}
+
+		if resp.Failure != nil {
+			// ...handle policy failure
+			logger.Printf("policy failure: %v", resp.Failure)
+		}
+	}
+}
+```