metadata

Documentation

Overview

Package metadata contains data structured produced by all API generators and consumed by all API clients and command line tools. These data structures include information about each resource exposed by the API. They describe the actions exposed by each resource in a way that a command line tool can easily consume. The idea is to expose one command per action, each action data structure thus describes the information required to define the action command line flags. The data structures also expose methods used by the client to parse the resource hrefs and extracts the to build the action URL in a generic way.

Index

• type Action
  • func (a *Action) MatchHref(href string) bool
  • func (a *Action) PathParamNames() []string
  • func (a *Action) PayloadParamNames() []string
  • func (a *Action) QueryParamNames() []string
  • func (a *Action) URL(vars []*PathVariable) (*ActionPath, error)
• type ActionParam
• type ActionPath
• type ByLen
  • func (b ByLen) Len() int
  • func (b ByLen) Less(i, j int) bool
  • func (b ByLen) Swap(i, j int)
• type ByWeight
  • func (b ByWeight) Len() int
  • func (b ByWeight) Less(i, j int) bool
  • func (b ByWeight) Swap(i, j int)
• type Location
• type PathPattern
  • func (p *PathPattern) Substitute(vars []*PathVariable) (string, []string)
• type PathVariable
• type Resource
  • func (r *Resource) ExtractVariables(href string) ([]*PathVariable, error)
  • func (r *Resource) GetAction(name string) *Action
  • func (r *Resource) HasLink(name string) bool

Types

type Action

type Action struct {
	Name         string
	Description  string
	PathPatterns []*PathPattern // Action path patterns and
	APIParams    []*ActionParam // Actual API request parameters
	CommandFlags []*ActionParam // Parameters initialized via command lines, these correspond to the leaves of all APIParams.
	Payload      string         // Name of payload type, only set for basic types
}

Action represents a resource action.

func (*Action) MatchHref

func (a *Action) MatchHref(href string) bool

MatchHref returns true if the given href matches one of the action's href patterns exactly

func (*Action) PathParamNames

func (a *Action) PathParamNames() []string

PathParamNames returns the names of the action path parameters sorted alphabetically.

func (*Action) PayloadParamNames

func (a *Action) PayloadParamNames() []string

PayloadParamNames returns the names of the action payload parameters sorted alphabetically.

func (*Action) QueryParamNames

func (a *Action) QueryParamNames() []string

QueryParamNames returns the names of the action query parameters sorted alphabetically.

func (*Action) URL

func (a *Action) URL(vars []*PathVariable) (*ActionPath, error)

URL returns a URL to the action given a set of values that can be used to substitute the action paths pattern variables. This method tries to use a many variables as possible so that "the longest" path gets used. So if for example an action has the patterns "/instances/:id" and "/clouds/:cloud_id/instances/:id" and both the :cloud_id and :id variable values are given as parameter, the method returns a URL built from substituting the values of the later (longer) path. The method returns an error in case no path pattern can have all its variables subsituted.

type ActionParam

type ActionParam struct {
	Name        string         // Param name
	Description string         // Param description
	Type        string         // Param type, one of "string", "[]string", "int", "[]int" or "map[string]string"
	Location    Location       // Param location, i.e. path, query or payload
	Mandatory   bool           // Whether parameter is mandatory
	NonBlank    bool           // Whether parameter value can be blank
	Regexp      *regexp.Regexp // Regular expression used to validate parameter values
	ValidValues []string       // List of valid values for parameter
}

ActionParam represents a resource action parameters.

type ActionPath

type ActionPath struct {
	Path       string // Actual path, e.g. "/clouds/1/instances/42"
	HTTPMethod string // HTTP method
	// contains filtered or unexported fields
}

ActionPath is a match built from a path pattern and given variable values.

type ByLen

type ByLen []*PathPattern

ByLen makes it possible to sort path patterns by length.

func (ByLen) Len

func (b ByLen) Len() int

func (ByLen) Less

func (b ByLen) Less(i, j int) bool

func (ByLen) Swap

func (b ByLen) Swap(i, j int)

type ByWeight

type ByWeight []*ActionPath

ByWeight makes it possible to sort path match by weight, from heaviest to lightest.

func (ByWeight) Len

func (b ByWeight) Len() int

func (ByWeight) Less

func (b ByWeight) Less(i, j int) bool

func (ByWeight) Swap

func (b ByWeight) Swap(i, j int)

type Location

type Location int

Location indicates a parameter location (i.e. URL path, query string or request body).

const (
	PathParam Location = iota
	QueryParam
	PayloadParam
)

Possible param location

type PathPattern

type PathPattern struct {
	HTTPMethod string         // "GET", "POST", "PUT", "DELETE", ...
	Pattern    string         // Actual pattern, e.g. "/clouds/%s/instances/%s"
	Variables  []string       // Pattern variable names in order of appearance in pattern, e.g. "cloud_id", "id"
	Regexp     *regexp.Regexp // Regexp used to match href and capture variable values, e.g. "/clouds/([^/]+)/instances/([^/])+"
}

PathPattern represents a possible path for a given action.

func (*PathPattern) Substitute

func (p *PathPattern) Substitute(vars []*PathVariable) (string, []string)

Substitute attemps to substitute the path pattern variables with the given values.

• If the substitution succeeds, it returns the resulting path and the list of variable names that were used to build it.
• If the substitution fails, it returns an empty string and the list of variable names that are missing from the list of given values.

type PathVariable

type PathVariable struct {
	Name  string // e.g. "cloud_id"
	Value string // e.g. "1"
}

PathVariable consists of a name and value.

type Resource

type Resource struct {
	Name        string
	Description string
	Actions     []*Action
	Identifier  string
	Links       map[string]string
}

Resource command

func (*Resource) ExtractVariables

func (r *Resource) ExtractVariables(href string) ([]*PathVariable, error)

ExtractVariables takes a resource href and extracts the variables (cloud_id, id etc.) that make it up. It does that by matching the href against all the resource action path patterns and finding the longest one that matches.

func (*Resource) GetAction

func (r *Resource) GetAction(name string) *Action

GetAction returns the action with the given name, returns nil if none is found.

func (*Resource) HasLink

func (r *Resource) HasLink(name string) bool

HasLink returns whether the resource has a link with the given name.