feat(api): refactor to generate parents/patterns/children

The previous version of the API struct required that
pointers to parents and children were also passed - this
isn't strictly possible with value serialization from Json / Yaml,
resulting in significantly complexity around deduplication of objects.

In addition, there were default values in loaded resources missing (such as path).

To resolve this, many of the api.Resource fields were turned semi-private, generated
on load, loading from an API associated with the resources. By lazy-generating these
values, it enables a minimal set of values to be specified in markup formats, while
still enabling these structs to be used in the code base itself. Ultimately, this
prevents the need to define an on-disk resource format and an in-memory format.

Author: toumorokoshi

examples/resource-definitions/bookstore.yaml

@@ -26,8 +26,7 @@ resources:
   book: &book
     singular: "book"
     plural: "books"
-    parents:
-      - *publisher
+    parents: ["publisher"]
     schema:
       type: object
       required: ["author", "edition", "isbn", "price", "published"]
@@ -59,7 +58,8 @@ resources:
                 type: string
                 x-aep-field-number: 2
     methods:
-      create: {}
+      create:
+        supports_user_settable_create: true
       read: {}
       update: {}
       delete: {}
@@ -80,8 +80,7 @@ resources:
   book-edition:
     singular: "book-edition"
     plural: "book-editions"
-    parents:
-      - *book
+    parents: ["book"]
     schema:
       type: object
       required: ["displayname"]

pkg/api/api.go

@@ -1,7 +1,6 @@
 package api
 
 import (
-	"encoding/json"
 	"fmt"
 	"log/slog"
 	"strings"
@@ -29,19 +28,6 @@ type Contact struct {
 	URL   string
 }
 
-func LoadAPIFromJson(data []byte) (*API, error) {
-	api := &API{}
-	err := json.Unmarshal(data, api)
-	if err != nil {
-		return nil, fmt.Errorf("error unmarshalling API: %v", err)
-	}
-	err = addImplicitFields(api)
-	if err != nil {
-		return nil, fmt.Errorf("error adding defaults to API: %v", err)
-	}
-	return api, nil
-}
-
 func GetAPI(api *openapi.OpenAPI, serverURL, pathPrefix string) (*API, error) {
 	if api.OASVersion() == "" {
 		return nil, fmt.Errorf("unable to detect OAS version. Please add a openapi field or a swagger field")
@@ -350,23 +336,26 @@ func getOrPopulateResource(singular string, pattern []string, s *openapi.Schema,
 			parents = append(parents, parentResource)
 			parentResource.Children = append(parentResource.Children, r)
 		}
+		patternElems := strings.Split(strings.TrimPrefix(s.XAEPResource.Patterns[0], "/"), "/")
 		r = &Resource{
-			Singular:     s.XAEPResource.Singular,
-			Plural:       s.XAEPResource.Plural,
-			Parents:      parents,
-			Children:     []*Resource{},
-			PatternElems: strings.Split(strings.TrimPrefix(s.XAEPResource.Patterns[0], "/"), "/"),
-			Schema:       s,
+			Singular:        s.XAEPResource.Singular,
+			Plural:          s.XAEPResource.Plural,
+			Parents:         s.XAEPResource.Parents,
+			parentResources: parents,
+			Children:        []*Resource{},
+			patternElems:    patternElems,
+			Schema:          s,
 		}
 	} else {
 		// best effort otherwise
 		r = &Resource{
-			Schema:       s,
-			PatternElems: pattern,
-			Singular:     singular,
-			Parents:      []*Resource{},
-			Children:     []*Resource{},
-			Plural:       plural(singular),
+			Schema:          s,
+			patternElems:    pattern,
+			Singular:        singular,
+			Parents:         []string{},
+			parentResources: []*Resource{},
+			Children:        []*Resource{},
+			Plural:          plural(singular),
 		}
 	}
 	resourceBySingular[singular] = r
@@ -408,19 +397,3 @@ func getContact(contact openapi.Contact) *Contact {
 func plural(singular string) string {
 	return singular + "s"
 }
-
-// addImplicitFields adds implicit fields to the API object,
-// such as the "path" variable in the resource.
-func addImplicitFields(api *API) error {
-	// add the path variable to the resource
-	for _, r := range api.Resources {
-		if r.Schema.Properties != nil {
-			r.Schema.Properties[constants.FIELD_PATH_NAME] = openapi.Schema{
-				Type:            "string",
-				Description:     "The server-assigned path of the resource, which is unique within the service.",
-				XAEPFieldNumber: constants.FIELD_PATH_NUMBER,
-			}
-		}
-	}
-	return nil
-}

pkg/api/api_test.go

@@ -180,7 +180,7 @@ func TestGetAPI(t *testing.T) {
 
 				widget, ok := sd.Resources["widget"]
 				assert.True(t, ok, "widget resource should exist")
-				assert.Equal(t, widget.PatternElems, []string{"widgets", "{widget}"})
+				assert.Equal(t, widget.PatternElems(), []string{"widgets", "{widget}"})
 				assert.Equal(t, sd.ServerURL, "https://api.example.com")
 				assert.NotNil(t, widget.Methods.Get, "should have GET method")
 				assert.NotNil(t, widget.Methods.List, "should have LIST method")
@@ -251,7 +251,7 @@ func TestGetAPI(t *testing.T) {
 				assert.True(t, ok, "widget resource should exist")
 				assert.Equal(t, "widget", widget.Singular)
 				assert.Equal(t, "widgets", widget.Plural)
-				assert.Equal(t, []string{"widgets", "{widget}"}, widget.PatternElems)
+				assert.Equal(t, []string{"widgets", "{widget}"}, widget.PatternElems())
 			},
 		},
 		{
@@ -333,7 +333,7 @@ func TestGetAPI(t *testing.T) {
 				widget, ok := sd.Resources["widget"]
 				assert.True(t, ok, "widget resource should exist")
 				assert.NotNil(t, widget.Methods.Get, "should have GET method")
-				assert.Equal(t, []string{"widgets", "{widget}"}, widget.PatternElems)
+				assert.Equal(t, []string{"widgets", "{widget}"}, widget.PatternElems())
 			},
 		},
 		{
@@ -574,7 +574,7 @@ func TestGetAPI(t *testing.T) {
 	}
 }
 
-func TestParseBookstoreYAMLDirectly(t *testing.T) {
+func TestLoadFromJsonBookstore(t *testing.T) {
 	// Construct the path relative to the test file's location
 	yamlPath := filepath.Join("..", "..", "examples", "resource-definitions", "bookstore.yaml")
 
@@ -587,6 +587,7 @@ func TestParseBookstoreYAMLDirectly(t *testing.T) {
 	require.NoError(t, err, "Failed to convert YAML to JSON")
 
 	apiResult, err := LoadAPIFromJson(jsonData)
+	require.NoError(t, err, "Failed to load API from JSON")
 	err = json.Unmarshal(jsonData, &apiResult)
 	require.NoError(t, err, "Failed to unmarshal JSON into api.API struct")
 
@@ -627,6 +628,7 @@ func TestParseBookstoreYAMLDirectly(t *testing.T) {
 	assert.Equal(t, "array", bookResource.Schema.Properties["isbn"].Type)
 	assert.NotNil(t, bookResource.Methods.List, "'book' should have List method")
 	assert.True(t, bookResource.Methods.List.HasUnreachableResources)
+	assert.True(t, bookResource.Methods.Create.SupportsUserSettableCreate)
 	assert.Len(t, bookResource.CustomMethods, 1, "'book' should have 1 custom method")
 	assert.Equal(t, "archive", bookResource.CustomMethods[0].Name)
 }

pkg/api/loader.go

@@ -0,0 +1,48 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/aep-dev/aep-lib-go/pkg/constants"
+	"github.com/aep-dev/aep-lib-go/pkg/openapi"
+)
+
+func LoadAPIFromJson(data []byte) (*API, error) {
+	api := &API{}
+	err := json.Unmarshal(data, api)
+	if err != nil {
+		return nil, fmt.Errorf("error unmarshalling API: %v", err)
+	}
+	err = addImplicitFields(api)
+	if err != nil {
+		return nil, fmt.Errorf("error adding defaults to API: %v", err)
+	}
+	return api, nil
+}
+
+// addImplicitFields adds implicit fields to the API object,
+// such as the "path" variable in the resource.
+func addImplicitFields(api *API) error {
+	// add the path variable to the resource
+	for _, r := range api.Resources {
+		r.API = api
+		if r.Schema.Properties == nil {
+			r.Schema.Properties = make(map[string]openapi.Schema)
+		}
+		r.Schema.Properties[constants.FIELD_PATH_NAME] = openapi.Schema{
+			Type:            "string",
+			Description:     "The server-assigned path of the resource, which is unique within the service.",
+			XAEPFieldNumber: constants.FIELD_PATH_NUMBER,
+		}
+		for _, p := range r.Parents {
+			if parent, ok := api.Resources[p]; ok {
+				r.parentResources = append(r.parentResources, parent)
+				parent.Children = append(parent.Children, r)
+			} else {
+				return fmt.Errorf("parent resource %s not found for resource %s", p, r.Singular)
+			}
+		}
+	}
+	return nil
+}

pkg/api/openapi.go

@@ -411,15 +411,11 @@ func ConvertToOpenAPI(api *API) (*openapi.OpenAPI, error) {
 				addMethodToPath(paths, cmPath, methodType, methodInfo)
 			}
 		}
-		parents := []string{}
-		for _, p := range r.Parents {
-			parents = append(parents, p.Singular)
-		}
 		d.XAEPResource = &openapi.XAEPResource{
 			Singular: r.Singular,
 			Plural:   r.Plural,
 			Patterns: patterns,
-			Parents:  parents,
+			Parents:  r.Parents,
 		}
 		components.Schemas[r.Singular] = *d
 	}
@@ -480,11 +476,11 @@ type PathWithParams struct {
 func generateParentPatternsWithParams(r *Resource) (string, *[]PathWithParams) {
 	// case 1: pattern elems are present, so we use them.
 	// TODO(yft): support multiple patterns
-	if len(r.PatternElems) > 0 {
-		collection := fmt.Sprintf("/%s", r.PatternElems[len(r.PatternElems)-2])
+	if len(r.patternElems) > 0 {
+		collection := fmt.Sprintf("/%s", r.patternElems[len(r.patternElems)-2])
 		params := []openapi.Parameter{}
-		for i := 0; i < len(r.PatternElems)-2; i += 2 {
-			pElem := r.PatternElems[i+1]
+		for i := 0; i < len(r.patternElems)-2; i += 2 {
+			pElem := r.patternElems[i+1]
 			params = append(params, openapi.Parameter{
 				In:       "path",
 				Name:     pElem[1 : len(pElem)-1],
@@ -494,7 +490,7 @@ func generateParentPatternsWithParams(r *Resource) (string, *[]PathWithParams) {
 				},
 			})
 		}
-		pattern := strings.Join(r.PatternElems[0:len(r.PatternElems)-2], "/")
+		pattern := strings.Join(r.patternElems[0:len(r.patternElems)-2], "/")
 		if pattern != "" {
 			pattern = fmt.Sprintf("/%s", pattern)
 		}
@@ -505,7 +501,7 @@ func generateParentPatternsWithParams(r *Resource) (string, *[]PathWithParams) {
 	// case 2: no pattern elems, so we need to generate the collection names
 	collection := fmt.Sprintf("/%s", CollectionName(r))
 	pwps := []PathWithParams{}
-	for _, parent := range r.Parents {
+	for _, parent := range r.ParentResources() {
 		singular := parent.Singular
 		basePattern := fmt.Sprintf("/%s/{%s}", CollectionName(parent), singular)
 		baseParam := openapi.Parameter{
@@ -519,7 +515,7 @@ func generateParentPatternsWithParams(r *Resource) (string, *[]PathWithParams) {
 				Resource: singular,
 			},
 		}
-		if len(parent.Parents) == 0 {
+		if len(parent.ParentResources()) == 0 {
 			pwps = append(pwps, PathWithParams{
 				Pattern: basePattern,
 				Params:  []openapi.Parameter{baseParam},

pkg/api/openapi_test.go

@@ -305,7 +305,7 @@ func TestGenerateParentPatternsWithParams(t *testing.T) {
 		{
 			name: "with pattern elements",
 			resource: &Resource{
-				PatternElems: []string{"databases", "{database}", "tables", "{table}"},
+				patternElems: []string{"databases", "{database}", "tables", "{table}"},
 				Singular:     "table",
 			},
 			wantCollection: "/tables",
@@ -331,7 +331,7 @@ func TestGenerateParentPatternsWithParams(t *testing.T) {
 		{
 			name: "with pattern elements no nesting",
 			resource: &Resource{
-				PatternElems: []string{"databases", "{database}"},
+				patternElems: []string{"databases", "{database}"},
 				Singular:     "database",
 			},
 			wantCollection: "/databases",
@@ -348,7 +348,7 @@ func TestGenerateParentPatternsWithParams(t *testing.T) {
 			resource: &Resource{
 				Singular: "table",
 				Plural:   "tables",
-				Parents: []*Resource{
+				parentResources: []*Resource{
 					{
 						Singular: "database",
 						Plural:   "databases",
@@ -380,11 +380,11 @@ func TestGenerateParentPatternsWithParams(t *testing.T) {
 			resource: &Resource{
 				Singular: "table",
 				Plural:   "tables",
-				Parents: []*Resource{
+				parentResources: []*Resource{
 					{
 						Singular: "database",
 						Plural:   "databases",
-						Parents: []*Resource{
+						parentResources: []*Resource{
 							{
 								Singular: "account",
 								Plural:   "accounts",