Merge pull request #99 from kim-tsao/doc_updates

Update Registry Library docs

Author: kim-tsao

registry-library/README.md

@@ -1,56 +1,96 @@
 # Devfile registry library
 
 ## Overview
-Devfile registry library is used for interacting with devfile registry, consumers can use devfile registry library to list stacks and/or samples of devfile registry, download the stack devfile and the whole stack from devfile registry.
+The Devfile registry library is used to interact with the devfile registry to perform the following actions:
+
+* List the indices of stacks and/or samples from a single registry or across multiple registries
+* Download a stack with specific media types or all supported media types
+* Send telemetry to the Devfile Registry service
+* Filter stacks based on architectures
 
 ## What's included
-`./library`: package `library` which contains devfile registry library constants, variables and functions, documentations can be found [here](https://pkg.go.dev/github.com/devfile/registry-support/registry-library/library)
+`./library`: package `library` which contains devfile registry library constants, variables and functions. Documentation can be found [here](https://pkg.go.dev/github.com/devfile/registry-support/registry-library/library)
 
-`./build.sh`: build script to build `registry` binary to interact with devfile registry
+`./build.sh`: build script to build the `registry-library` binary to interact with devfile registry
 
-`./registry`: `registry` binary to interact with devfile registry
+`./registry-library`: `registry-library` binary to interact with devfile registry
 
 ## How to use it
-1. Import devfile registry library
-```go
-import (
-    registryLibrary "github.com/devfile/registry-support/registry-library/library"
-)
-```
-2. Invoke devfile registry library
-
-    a. Get the index of devfile registry for various devfile types
-    ```go
-    registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, StackDevfileType)
-	if err != nil {
-		return err
-	}
+1. Import the devfile registry library and index schema
+   ```go
+   import (
+       registryLibrary "github.com/devfile/registry-support/registry-library/library"
+       indexSchema "github.com/devfile/registry-support/index/generator/schema"
+   )
+   ```
+
+### List the indices of stacks and/or samples
+1. Get the index for stack devfile types from a single registry
+
+    ```go
+    registryURL := "https://registry.devfile.io"
+    options := registryLibrary.RegistryOptions{} //leave empty if telemetry and architecture types are not relevant
+    registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, indexSchema.StackDevfileType)
+    if err != nil {
+        return err
+    }
     ```
-    b. Get the indices of multiple devfile registries for various devfile types
+2. Get the index for all devfile types from a single registry
     ```go
-    registryList := GetMultipleRegistryIndices(registryURLs, options, StackDevfileType)
+   devfileTypes := []indexSchema.DevfileType{indexSchema.StackDevfileType, indexSchema.SampleDevfileType}
+   registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, devfileTypes...)
+   if err != nil {
+   return err
+   }
     ```
-    c. Download the stack devfile from devfile registry
+
+3. Get the indices for various devfile stacks from multiple devfile registries
     ```go
-	err := registryLibrary.PullStackByMediaTypesFromRegistry(registry, stack, registryLibrary.DevfileMediaTypeList, destDir, options)
-	if err != nil {
-		return err
-	}
+    registryList := GetMultipleRegistryIndices(registryURLs, options, indexSchema.StackDevfileType)
     ```
-    d. Download the whole stack from devfile registry
+#### Download the stack 
+Supported devfile media types can be found in the latest version of [library.go](https://github.com/devfile/registry-support/blob/main/registry-library/library/library.go)
+1. Download a stack devfile with a given media type from the devfile registry
     ```go
-    err := registryLibrary.PullStackFromRegistry(registry, stack, destDir, options)
+    stack := "java-springboot"
+    destDir := "."
+    err := registryLibrary.PullStackByMediaTypesFromRegistry(registryURL, stack, registryLibrary.DevfileMediaTypeList, destDir, options)
     if err != nil {
-		return err
-	}
+        return err
+    }
     ```
-    e. Specify Options
+2. Download a stack with all supported media types from the devfile registry
     ```go
-    options := RegistryOptions{
-        User:          user,
-        SkipTLSVerify: skipTLSVerify,
-        Filter:        RegistryFilter{
+    err := registryLibrary.PullStackFromRegistry(registryURL, stack, destDir, options)
+    if err != nil {
+        return err
+    }
+    ```
+
+#### Specify Registry Options
+1. Test a pre-prod registry installed with self-signed certificates
+    ```go
+    options := registryLibrary.RegistryOptions{
+        SkipTLSVerify: "true",
+    }
+    ```
+2. Filter Devfiles based on a set of architectures found in [header.go](https://github.com/devfile/api/blob/main/pkg/devfile/header.go)
+    ```go
+    architectures := []string{"amd64", "arm64"}
+    options := registryLibrary.RegistryOptions{
+        Filter: registryLibrary.RegistryFilter{
             Architectures: architectures,
         },
     }
     ```
+3. Send Telemetry data to the Devfile Registry
+    ```go
+    options := registryLibrary.RegistryOptions{
+        Telemetry: registryLibrary.TelemetryData{
+            User:   "user-name" //this can be a generated UUID
+            Locale: "en_US" // set the OS or browser locale
+            Client: "client-name" //the name of the client
+        }
+} 
+
+

registry-library/library/library.go

@@ -39,8 +39,7 @@ import (
 )
 
 const (
-	// Devfile media types
-	DevfileConfigMediaType  = "application/vnd.devfileio.devfile.config.v2+json"
+	// Supported Devfile media types
 	DevfileMediaType        = "application/vnd.devfileio.devfile.layer.v1"
 	DevfileVSXMediaType     = "application/vnd.devfileio.vsx.layer.v1.tar"
 	DevfileSVGLogoMediaType = "image/svg+xml"
@@ -63,28 +62,33 @@ type Registry struct {
 }
 
 //TelemetryData structure to pass in client telemetry information
+// The User and Locale fields should be passed in by clients if telemetry opt-in is enabled
+// the generic Client name will be passed in regardless of opt-in/out choice.  The value
+// will be assigned to the UserId field for opt-outs
 type TelemetryData struct {
-	// The User and Locale fields will be passed in by the clients if telemetry opt-in is enabled
-	User   string
+	// User is a generated UUID or generic client name
+	User string
+	// Locale is the OS or browser locale
 	Locale string
-	// the generic client name will be passed in regardless of opt-in/out choice.  The value
-	// will be assigned to the UserId field for opt-outs
+	//Client is a generic name that describes the client
 	Client string
 }
 
 type RegistryOptions struct {
+	// SkipTLSVerify is false by default which is the recommended setting for a devfile registry deployed in production.  SkipTLSVerify should only be set to true
+	// if you are testing a devfile registry that is set up with self-signed certificates in a pre-production environment.
 	SkipTLSVerify bool
-	Telemetry     TelemetryData
-	Filter        RegistryFilter
+	// Telemetry allows clients to send telemetry data to the community Devfile Registry
+	Telemetry TelemetryData
+	// Filter allows clients to specify which architectures they want to filter their devfiles on
+	Filter RegistryFilter
 }
 
 type RegistryFilter struct {
 	Architectures []string
 }
 
-// GetRegistryIndex returns the list of stacks and/or samples, more specifically
-// it gets the stacks and/or samples content of the index of the specified registry
-// for listing the stacks and/or samples
+// GetRegistryIndex returns the list of index schema structured stacks and/or samples from a specified devfile registry.
 func GetRegistryIndex(registryURL string, options RegistryOptions, devfileTypes ...indexSchema.DevfileType) ([]indexSchema.Schema, error) {
 	var registryIndex []indexSchema.Schema
 
@@ -162,7 +166,7 @@ func GetRegistryIndex(registryURL string, options RegistryOptions, devfileTypes
 	return registryIndex, nil
 }
 
-// GetMultipleRegistryIndices returns returns the list of stacks and/or samples of multiple registries
+// GetMultipleRegistryIndices returns the list of stacks and/or samples from multiple registries
 func GetMultipleRegistryIndices(registryURLs []string, options RegistryOptions, devfileTypes ...indexSchema.DevfileType) []Registry {
 	registryList := make([]Registry, len(registryURLs))
 	registryContentsChannel := make(chan []indexSchema.Schema)
@@ -210,7 +214,7 @@ func PrintRegistry(registryURLs string, devfileType string, options RegistryOpti
 	return nil
 }
 
-// PullStackByMediaTypesFromRegistry pulls stack from registry with allowed media types to the destination directory
+// PullStackByMediaTypesFromRegistry pulls a specified stack with allowed media types from a given registry URL to the destination directory
 func PullStackByMediaTypesFromRegistry(registry string, stack string, allowedMediaTypes []string, destDir string, options RegistryOptions) error {
 	// Get the registry index
 	registryIndex, err := GetRegistryIndex(registry, options, indexSchema.StackDevfileType)
@@ -278,7 +282,7 @@ func PullStackByMediaTypesFromRegistry(registry string, stack string, allowedMed
 	return nil
 }
 
-// PullStackFromRegistry pulls stack from registry with all stack resources (all media types) to the destination directory
+// PullStackFromRegistry pulls a specified stack with all devfile supported media types from a registry URL to the destination directory
 func PullStackFromRegistry(registry string, stack string, destDir string, options RegistryOptions) error {
 	return PullStackByMediaTypesFromRegistry(registry, stack, DevfileAllMediaTypesList, destDir, options)
 }