Improve semantics for listing methods

.codegen/api.go.tmpl

@@ -162,8 +162,11 @@ func (a *{{.Service.Name}}API) {{.PascalName}}AndWait(ctx context.Context{{if .R
 {{.Comment "// " 80}}
 // 
 // This method is generated by Databricks SDK Code Generator.
-func (a *{{.Service.Name}}API) {{.PascalName}}All(ctx context.Context{{if .Request}}, request {{.Request.PascalName}}{{end}}) ([]{{.Pagination.Entity.PascalName}}, error) {
+func (a *{{.Service.Name}}API) {{.PascalName}}All(ctx context.Context{{if .ListingRequest}}, listing {{.ListingRequest.PascalName}}{{end}}) ([]{{.Pagination.Entity.PascalName}}, error) {
 	{{if .Pagination.MultiRequest}}var results []{{.Pagination.Entity.PascalName}}
+	{{if .ListingRequest}}request := {{.Request.PascalName}}{ {{range .ListingRequest.Fields }}
+		{{.PascalName}}: listing.{{.PascalName}},{{end}}
+	}{{end}}
 	{{ if .Pagination.Limit -}}
 	var totalCount {{template "type" .Pagination.Limit.Entity}} = 0
 	{{ end -}}
@@ -203,6 +206,7 @@ func (a *{{.Service.Name}}API) {{.PascalName}}All(ctx context.Context{{if .Reque
 		if response.NextPage == nil {
 			break
 		}
+		// cluster events API returns next page information as part of the result
 		request = *response.NextPage
 		{{- else if .Pagination.Token -}}
 		request.{{.Pagination.Token.PollField.PascalName}} = response.{{.Pagination.Token.Bind.PascalName}}
@@ -221,11 +225,11 @@ func (a *{{.Service.Name}}API) {{.PascalName}}All(ctx context.Context{{if .Reque
 		}
 		{{- end -}}
 	}
-	return results, nil{{else if .Pagination.Results}}response, err := a.impl.{{.PascalName}}(ctx{{if .Request}}, request{{end}})
+	return results, nil{{else if .Pagination.Results}}response, err := a.impl.{{.PascalName}}(ctx{{if .Request}}, listing{{end}})
 	if err != nil {
 		return nil, err
 	}
-	return response.{{.Pagination.Results.PascalName}}, nil{{else}}return a.impl.{{.PascalName}}(ctx, request){{end}}
+	return response.{{.Pagination.Results.PascalName}}, nil{{else}}return a.impl.{{.PascalName}}(ctx, listing){{end}}
 }
 {{end}}{{if .NamedIdMap}}
 // {{.NamedIdMap.PascalName}} calls [{{.Service.Name}}API.{{.PascalName}}{{if not .NamedIdMap.Direct}}All{{end -}}] and creates a map of results with [{{.NamedIdMap.Entity.PascalName}}]{{ template "field-path" .NamedIdMap.NamePath }} as key and [{{.NamedIdMap.Entity.PascalName}}]{{ template "field-path" .NamedIdMap.IdPath}} as value.
@@ -235,10 +239,10 @@ func (a *{{.Service.Name}}API) {{.PascalName}}All(ctx context.Context{{if .Reque
 // Note: All [{{.NamedIdMap.Entity.PascalName}}] instances are loaded into memory before creating a map.
 // 
 // This method is generated by Databricks SDK Code Generator.
-func (a *{{.Service.Name}}API) {{.NamedIdMap.PascalName}}(ctx context.Context{{if .Request}}, request {{.Request.PascalName}}{{end}}) (map[string]{{template "type" .NamedIdMap.Id.Entity}}, error) {
+func (a *{{.Service.Name}}API) {{.NamedIdMap.PascalName}}(ctx context.Context{{if .ListingRequest}}, listing {{.ListingRequest.PascalName}}{{end}}) (map[string]{{template "type" .NamedIdMap.Id.Entity}}, error) {
 	ctx = useragent.InContext(ctx, "sdk-feature", "name-to-id")
 	mapping := map[string]{{template "type" .NamedIdMap.Id.Entity}}{}
-	result, err := a.{{.PascalName}}{{if not .NamedIdMap.Direct}}All{{end}}(ctx{{if .Request}}, request{{end}})
+	result, err := a.{{.PascalName}}{{if not .NamedIdMap.Direct}}All{{end}}(ctx{{if .ListingRequest}}, listing{{end}})
 	if err != nil {
 		return nil, err
 	}
@@ -262,7 +266,7 @@ func (a *{{.Service.Name}}API) {{.NamedIdMap.PascalName}}(ctx context.Context{{i
 // This method is generated by Databricks SDK Code Generator.
 func (a *{{.Service.Name}}API) GetBy{{range .NamedIdMap.NamePath}}{{.PascalName}}{{end}}(ctx context.Context, name string) (*{{template "type" .GetByName}}, error) {
 	ctx = useragent.InContext(ctx, "sdk-feature", "get-by-name")
-	result, err := a.{{.PascalName}}{{if not .NamedIdMap.Direct}}All{{end}}(ctx{{if .Request}}, {{.Request.PascalName}}{}{{end}})
+	result, err := a.{{.PascalName}}{{if not .NamedIdMap.Direct}}All{{end}}(ctx{{if .ListingRequest}}, {{.ListingRequest.PascalName}}{}{{end}})
 	if err != nil {
 		return nil, err
 	}

openapi/code/method.go

@@ -20,6 +20,8 @@ type Method struct {
 	PathParts []PathPart
 	// Request type representation
 	Request *Entity
+	// Request for listing
+	ListingRequest *Entity
 	// Response type representation
 	Response          *Entity
 	EmptyResponseName Named

openapi/code/service.go

@@ -304,6 +304,7 @@ func (svc *Service) newMethod(verb, path string, params []openapi.Parameter, op
 		Verb:              strings.ToUpper(verb),
 		Path:              path,
 		Request:           request,
+		ListingRequest:    svc.withPaginationFieldsRemoved(request, op.Pagination),
 		PathParts:         svc.paramPath(path, request, params),
 		Response:          response,
 		EmptyResponseName: emptyResponse,
@@ -317,6 +318,83 @@ func (svc *Service) newMethod(verb, path string, params []openapi.Parameter, op
 	}
 }
 
+// remove pagination fields without clear semantics for iterators
+func (svc *Service) withPaginationFieldsRemoved(req *Entity, pg *openapi.Pagination) *Entity {
+	if req == nil {
+		return nil
+	}
+	if svc.Name == "Clusters" && req.CamelName() == "getEvents" {
+		// edge case: cluster events performs listing through POST, not GET
+		// all other listing requests entities are synthesized.
+		return req
+	}
+	if pg == nil || pg.Inline {
+		return req
+	}
+	listing := &Entity{
+		Named: Named{
+			Name:        req.PascalName(),
+			Description: req.Description,
+		},
+		Package:       req.Package,
+		RequiredOrder: req.RequiredOrder,
+		fields:        map[string]*Field{},
+	}
+	var requiresModification bool
+	for _, v := range req.fields {
+		field := v
+		var nextToken string
+		if pg.Token != nil {
+			nextToken = pg.Token.Request
+		}
+		switch field.Name {
+		case pg.Limit, pg.Offset, nextToken:
+			requiresModification = true
+			continue
+		}
+		listing.fields[field.Name] = field
+	}
+	if !requiresModification {
+		// there was no change. A bit strange.
+		return req
+	}
+	if svc.Name == "Jobs" {
+		// add generation for client-side maximum number of results during iteration.
+		// platform already implements this field for part of the APIs and it's
+		// consistently named as max_results everywhere. Perhaps we should
+		// rename "limit" to "max_results" in Jobs and add that to Dashboards and
+		// Queries as well, as we have exactly the same problem on big workspaces.
+		pg.Limit = "limit"
+		listing.fields["limit"] = &Field{
+			Named: Named{
+				Name:        "limit",
+				Description: "limit maximum number of results on the client side",
+			},
+			Of:      listing,
+			IsJson:  false,
+			IsQuery: false,
+			IsPath:  false,
+			Entity: &Entity{
+				IsInt: true,
+			},
+		}
+	}
+	if len(listing.fields) == 0 {
+		// there is no fields left
+		return nil
+	}
+	oldName := req.Name
+	_, needsRename := svc.Package.types[oldName]
+	if needsRename {
+		newName := strings.TrimSuffix(req.PascalName(), "Request") + "Internal"
+		req.Name = newName
+		req.Description = "For internal use only"
+		delete(svc.Package.types, oldName)
+		svc.Package.types[newName] = req
+	}
+	return svc.Package.define(listing)
+}
+
 func (svc *Service) HasWaits() bool {
 	for _, v := range svc.methods {
 		if v.wait != nil {