openapi

package
v0.49.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 14, 2024 License: Apache-2.0 Imports: 6 Imported by: 1

Documentation

Index

Constants

View Source 
const INVALID_PARAMETER_VALUE = "INVALID_PARAMETER_VALUE"
View Source 
const MediaTypeNonJsonBodyFieldName = "contents"
View Source 
const RESOURCE_DOES_NOT_EXIST = "RESOURCE_DOES_NOT_EXIST"

Variables

View Source 
var ErrorCodeMapping = []ErrorMappingRule{
	{400, "INVALID_STATE", "unexpected state"},
	{400, INVALID_PARAMETER_VALUE, "supplied value for a parameter was invalid"},
	{404, RESOURCE_DOES_NOT_EXIST, "operation was performed on a resource that does not exist"},
	{409, "ABORTED", "the operation was aborted, typically due to a concurrency issue such as a sequencer check failure"},
	{409, "ALREADY_EXISTS", "operation was rejected due a conflict with an existing resource"},
	{409, "RESOURCE_ALREADY_EXISTS", "operation was rejected due a conflict with an existing resource"},
	{429, "RESOURCE_EXHAUSTED", "operation is rejected due to per-user rate limiting"},
	{429, "REQUEST_LIMIT_EXCEEDED", "cluster request was rejected because it would exceed a resource limit"},
	{500, "UNKNOWN", "this error is used as a fallback if the platform-side mapping is missing some reason"},
	{500, "DATA_LOSS", "unrecoverable data loss or corruption"},
}

Specialized API error rules based on the error_code field in the error response.

See the documentation on ErrorStatusCodeMapping for more information.

View Source 
var ErrorOverrides = []ErrorOverride{
	{
		Name:              "Clusters InvalidParameterValue=>ResourceDoesNotExist",
		PathRegex:         regexp.MustCompile(`^/api/2\.\d/clusters/get`),
		Verb:              "GET",
		StatusCodeMatcher: regexp.MustCompile(`^400$`),
		MessageMatcher:    regexp.MustCompile("Cluster .* does not exist"),
		ErrorCodeMatcher:  regexp.MustCompile(INVALID_PARAMETER_VALUE),
		OverrideErrorCode: RESOURCE_DOES_NOT_EXIST,
	},
	{
		Name:              "Jobs InvalidParameterValue=>ResourceDoesNotExist",
		PathRegex:         regexp.MustCompile(`^/api/2\.\d/jobs/get`),
		Verb:              "GET",
		StatusCodeMatcher: regexp.MustCompile(`^400$`),
		MessageMatcher:    regexp.MustCompile("Job .* does not exist"),
		ErrorCodeMatcher:  regexp.MustCompile(INVALID_PARAMETER_VALUE),
		OverrideErrorCode: RESOURCE_DOES_NOT_EXIST,
	},
	{
		Name:              "Job Runs InvalidParameterValue=>ResourceDoesNotExist",
		PathRegex:         regexp.MustCompile(`^/api/2\.\d/jobs/runs/get`),
		Verb:              "GET",
		StatusCodeMatcher: regexp.MustCompile(`^400$`),
		MessageMatcher:    regexp.MustCompile("(Run .* does not exist|Run: .* in job: .* doesn't exist)"),
		ErrorCodeMatcher:  regexp.MustCompile(INVALID_PARAMETER_VALUE),
		OverrideErrorCode: RESOURCE_DOES_NOT_EXIST,
	},
}

Overrides in the SDK to remap specific error responses to other errors.

When certain APIs return a non-standard or inconsistent error response, the SDK can be configured to remap these errors to a more appropriate error. For example, some APIs return a 400 error when a resource doesn't exist. In this case, the SDK can be configured to remap the error to a 404 error.

View Source 
var ErrorStatusCodeMapping = []ErrorMappingRule{
	{400, "BAD_REQUEST", "the request is invalid"},
	{401, "UNAUTHENTICATED", "the request does not have valid authentication (AuthN) credentials for the operation"},
	{403, "PERMISSION_DENIED", "the caller does not have permission to execute the specified operation"},
	{404, "NOT_FOUND", "the operation was performed on a resource that does not exist"},
	{409, "RESOURCE_CONFLICT", "maps to all HTTP 409 (Conflict) responses"},
	{429, "TOO_MANY_REQUESTS", "maps to HTTP code: 429 Too Many Requests"},
	{499, "CANCELLED", "the operation was explicitly canceled by the caller"},
	{500, "INTERNAL_ERROR", "some invariants expected by the underlying system have been broken"},
	{501, "NOT_IMPLEMENTED", "the operation is not implemented or is not supported/enabled in this service"},
	{503, "TEMPORARILY_UNAVAILABLE", "the service is currently unavailable"},
	{504, "DEADLINE_EXCEEDED", "the deadline expired before the operation could complete"},
}

API error rules for the Databricks REST API based on HTTP status codes.

The API responds with an error by setting the HTTP status code to 400 or higher and returning a JSON object with an error code and message. Error responses are hierarchical in nature, with the HTTP status code providing the highest level of categorization. The error_code field in the response provides a more granular categorization of the error.

The SDK attempts to map these error responses to error objects based on this mapping by applying the following logic:

  1. If the error matches an override defined in ErrorOverrides, return the override.
  2. If the error_code field of the response matches a key in ErrorCodeMapping, return that error.
  3. If the HTTP status code matches a rule in ErrorStatusCodeMapping, return that error.
View Source 
var TransientErrorRegexes = []*regexp.Regexp{
	regexp.MustCompile(`com\.databricks\.backend\.manager\.util\.UnknownWorkerEnvironmentException`),
	regexp.MustCompile(`does not have any associated worker environments`),
	regexp.MustCompile(`There is no worker environment with id`),
	regexp.MustCompile(`Unknown worker environment`),
	regexp.MustCompile(`ClusterNotReadyException`),
	regexp.MustCompile(`worker env .* not found`),
	regexp.MustCompile(`Timed out after `),
	regexp.MustCompile(`deadline exceeded`),
}

Functions

This section is empty.

Types

type Binding 

type Binding struct {
	Request  string `json:"request,omitempty"`
	Response string `json:"response,omitempty"`
}

Binding is a relationship between request and/or response

type Body 

type Body struct {
	Node
	Required bool                  `json:"required,omitempty"`
	Content  map[string]MediaType  `json:"content,omitempty"`
	Headers  map[string]*Parameter `json:"headers,omitempty"`
}

func (*Body) MimeTypeAndMediaType added in v0.18.0 

func (b *Body) MimeTypeAndMediaType() (MimeType, *MediaType)

type Components 

type Components struct {
	Node
	Parameters refs[*Parameter] `json:"parameters,omitempty"`
	Responses  refs[*Body]      `json:"responses,omitempty"`
	Schemas    refs[*Schema]    `json:"schemas,omitempty"`
}

type DataPlane added in v0.43.1 

type DataPlane struct {
	ConfigMethod string   `json:"configMethod"`
	Fields       []string `json:"field"`
}

DataPlane is the Databricks OpenAPI Extension for direct access to DataPlane APIs

type ErrorMappingRule added in v0.26.0 

type ErrorMappingRule struct {
	StatusCode  int    `json:"status_code"`
	ErrorCode   string `json:"error_code"`
	Description string `json:"description"`
}

type ErrorOverride added in v0.38.0 

type ErrorOverride struct {
	Name              string
	PathRegex         *regexp.Regexp
	Verb              string
	StatusCodeMatcher *regexp.Regexp
	ErrorCodeMatcher  *regexp.Regexp
	MessageMatcher    *regexp.Regexp
	OverrideErrorCode string
}

type MediaType added in v0.18.0 

type MediaType struct {
	Node
	Schema *Schema `json:"schema,omitempty"`
}

func (*MediaType) GetSchema added in v0.18.0 

func (m *MediaType) GetSchema() *Schema

type MimeType added in v0.18.0 

type MimeType string
const (
	MimeTypeJson        MimeType = "application/json"
	MimeTypeOctetStream MimeType = "application/octet-stream"
	MimeTypeTextPlain   MimeType = "text/plain"
)

func (MimeType) IsByteStream added in v0.18.0 

func (m MimeType) IsByteStream() bool

IsByteStream returns true if the body should be modeled as a byte stream. Today, we only support application/json and application/octet-stream, and non application/json entities are all modeled as byte streams.

type Node 

type Node struct {
	Description string `json:"description,omitempty"`
	Preview     string `json:"x-databricks-preview,omitempty"`
	Ref         string `json:"$ref,omitempty"`
	// Currently it is only defined for top level schemas
	JsonPath string `json:"-"`
}

func (*Node) Component 

func (n *Node) Component() string

Components is the basename of the reference path. Usually a class name

func (*Node) IsRef 

func (n *Node) IsRef() bool

IsRef flags object being a reference to a component

type Operation 

type Operation struct {
	Node
	Wait       *Wait       `json:"x-databricks-wait,omitempty"`
	Pagination *Pagination `json:"x-databricks-pagination,omitempty"`
	DataPlane  *DataPlane  `json:"x-databricks-dataplane,omitempty"`
	Shortcut   bool        `json:"x-databricks-shortcut,omitempty"`
	Crud       string      `json:"x-databricks-crud,omitempty"`
	JsonOnly   bool        `json:"x-databricks-cli-json-only,omitempty"`

	// The x-databricks-path-style field indicates whether the operation has a
	// RESTful path style or a RPC style. When specified, this overrides the
	// service-level setting. Valid values are "rest" and "rpc". "rest" means
	// that the operation has a RESTful path style, i.e. the path represents
	// a resource and the HTTP method represents an action on the resource.
	// "rpc" means that the operation has a RPC style, i.e. the path represents
	// an action and the request body represents the resource.
	PathStyle PathStyle `json:"x-databricks-path-style,omitempty"`

	// The x-databricks-request-type-name field defines the name to use for
	// the request type in the generated client. This may be specified only
	// if the operation does NOT have a request body, thus only uses a request
	// type to encapsulate path and query parameters.
	RequestTypeName string `json:"x-databricks-request-type-name,omitempty"`

	// For list APIs, the path to the field in the response entity that contains
	// the resource ID.
	IdField fieldPath `json:"x-databricks-id,omitempty"`

	// For list APIs, the path to the field in the response entity that contains
	// the user-friendly name of the resource.
	NameField fieldPath `json:"x-databricks-name,omitempty"`

	Summary     string           `json:"summary,omitempty"`
	OperationId string           `json:"operationId"`
	Tags        []string         `json:"tags"`
	Parameters  []Parameter      `json:"parameters,omitempty"`
	Responses   map[string]*Body `json:"responses"`
	RequestBody *Body            `json:"requestBody,omitempty"`
}

Operation is the equivalent of method

func (*Operation) HasIdentifierField added in v0.13.0 

func (o *Operation) HasIdentifierField() bool

func (*Operation) HasNameField added in v0.13.0 

func (o *Operation) HasNameField() bool

func (*Operation) HasTag 

func (o *Operation) HasTag(tag string) bool

func (*Operation) Name 

func (o *Operation) Name() string

Name is picking the last element of <ServiceName>.<method> string, that is coming in as part of Databricks OpenAPI spec.

func (*Operation) SuccessResponseBody added in v0.18.0 

func (o *Operation) SuccessResponseBody(c *Components) *Body

type Pagination 

type Pagination struct {
	Offset    string   `json:"offset,omitempty"`
	Limit     string   `json:"limit,omitempty"`
	Results   string   `json:"results,omitempty"`
	Increment int      `json:"increment,omitempty"`
	Inline    bool     `json:"inline,omitempty"`
	Token     *Binding `json:"token,omitempty"`
}

Pagination is the Databricks OpenAPI Extension for retrieving lists of entities through multiple API calls

type Parameter 

type Parameter struct {
	Node
	Required     bool    `json:"required,omitempty"`
	In           string  `json:"in,omitempty"`
	Name         string  `json:"name,omitempty"`
	MultiSegment bool    `json:"x-databricks-multi-segment,omitempty"`
	Schema       *Schema `json:"schema,omitempty"`
}

type Path 

type Path struct {
	Node
	Parameters []Parameter `json:"parameters,omitempty"`
	Get        *Operation  `json:"get,omitempty"`
	Head       *Operation  `json:"head,omitempty"`
	Post       *Operation  `json:"post,omitempty"`
	Put        *Operation  `json:"put,omitempty"`
	Patch      *Operation  `json:"patch,omitempty"`
	Delete     *Operation  `json:"delete,omitempty"`
}

func (*Path) Verbs 

func (path *Path) Verbs() map[string]*Operation

Verbs returns a map of HTTP methods for a Path

type PathStyle added in v0.14.1 

type PathStyle string
const (
	// PathStyleRpc indicates that the endpoint is an RPC-style endpoint.
	// The endpoint path is an action, and the entity to act on is specified
	// in the request body.
	PathStyleRpc PathStyle = "rpc"

	// PathStyleRest indicates that the endpoint is a REST-style endpoint.
	// The endpoint path is a resource, and the operation to perform on the
	// resource is specified in the HTTP method.
	PathStyleRest PathStyle = "rest"
)

func (*PathStyle) UnmarshalJSON added in v0.14.1 

func (r *PathStyle) UnmarshalJSON(data []byte) error

type Schema 

type Schema struct {
	Node
	IsComputed       bool               `json:"x-databricks-computed,omitempty"`
	IsAny            bool               `json:"x-databricks-any,omitempty"`
	Type             string             `json:"type,omitempty"`
	Enum             []string           `json:"enum,omitempty"`
	AliasEnum        []string           `json:"x-databricks-alias-enum,omitempty"`
	EnumDescriptions map[string]string  `json:"x-databricks-enum-descriptions,omitempty"`
	Default          any                `json:"default,omitempty"`
	Example          any                `json:"example,omitempty"`
	Format           string             `json:"format,omitempty"`
	Required         []string           `json:"required,omitempty"`
	Properties       map[string]*Schema `json:"properties,omitempty"`
	ArrayValue       *Schema            `json:"items,omitempty"`
	MapValue         *Schema            `json:"additionalProperties,omitempty"`
	Terraform        *Terraform         `json:"x-databricks-terraform,omitempty"`
}

func (*Schema) IsArray 

func (s *Schema) IsArray() bool

func (*Schema) IsEnum 

func (s *Schema) IsEnum() bool

func (*Schema) IsMap 

func (s *Schema) IsMap() bool

func (*Schema) IsObject 

func (s *Schema) IsObject() bool

type Specification 

type Specification struct {
	Node
	Paths      map[string]Path `json:"paths"`
	Components *Components     `json:"components"`
	Tags       []Tag           `json:"tags"`
}

func NewFromReader 

func NewFromReader(r io.Reader) (*Specification, error)

func (*Specification) GetTagByServiceName added in v0.34.0 

func (s *Specification) GetTagByServiceName(name string) (*Tag, error)

type Tag 

type Tag struct {
	Node
	Package             string    `json:"x-databricks-package"`
	PathStyle           PathStyle `json:"x-databricks-path-style"`
	Service             string    `json:"x-databricks-service"`
	ParentService       string    `json:"x-databricks-parent-service"`
	ControlPlaneService string    `json:"x-databricks-controlplane"`
	IsAccounts          bool      `json:"x-databricks-is-accounts"`
	Name                string    `json:"name"`
}

type Terraform added in v0.45.0 

type Terraform struct {
	Alias string `json:"alias,omitempty"`
}

type Wait 

type Wait struct {
	Poll         string             `json:"poll"`
	Bind         string             `json:"bind"`
	BindResponse string             `json:"bindResponse,omitempty"`
	Binding      map[string]Binding `json:"binding,omitempty"`
	Field        []string           `json:"field"`
	Message      []string           `json:"message"`
	Success      []string           `json:"success"`
	Failure      []string           `json:"failure"`
	Timeout      int                `json:"timeout,omitempty"`
}

Wait is the Databricks OpenAPI Extension for long-running result polling

Source Files

View all Source files

Directories

Path Synopsis
Package holds higher-level abstractions on top of OpenAPI that are used to generate code via text/template for Databricks SDK in different languages.
 Package holds higher-level abstractions on top of OpenAPI that are used to generate code via text/template for Databricks SDK in different languages.
Usage: openapi-codegen
 Usage: openapi-codegen

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.