rest

README

REST

This library reads attributes (i.e. annotations) in Babel files that represent RESTful service metadata.

Scope

All of the supported attributes must use the @rest scope.

Operation

The Op attribute may be used on a method to describe the RESTful operation.

Option	Type	Default	Description
Path	string	"/"	The URL path.
Method	string	"GET"	The HTTP method. (GET, PUT, POST, DELETE, OPTIONS, HEAD, or PATCH).
Deprecated	bool	false	Whether this method is deprecated.
Hide	bool	false	Whether to hide this operation from tools like babel2swagger.

Example

@rest [Op(Path="/test/{a}/parms", Method="POST", Deprecated=true)]

Response

Additional responses may be defined with the Response attribute. It is only valid on methods.

Option	Type	Default	Description
Code	int	0	The HTTP response code.
Type	string	""	The Babel data type of the response. Defaults to the return type of the method.
Desc	string	""	Description of the response
Headers	string	""	A comma-separated list of header names. There must be a Header attribute with the same name.

Example

@rest [Response(Code=0, Type="string", Headers="Foo,Bar")]

Header

The Header attribute defines an HTTP headers that is returned.

Option	Type	Default	Description
Name	string	""	The HTTP header name.
Type	string	""	The Babel data type of the header.
Desc	string	""	Description of the header.
Format	string	""	The collection format of the data (applicable to list types): csv, ssv, tsv, pipes, multi.

Example

@rest [Header(Name="Foo", Type="string", Desc="Some header"),
       Header(Name="Bar", Type="list<string>", Format="csv" Desc="Some other header")]

Parameter

The Parm attribute defines where to pull variables from in the REST invocation.

Option	Type	Default	Description
In	string	"query"	Where the field is located: query, header, path, formdata, body.
Required	bool	false	Whether the field is required.
Format	string	""	The collection format of the data (applicable to list types): csv, ssv, tsv, pipes, multi.
Name	string	""	Used to rename a parameter (usually for headers)

Example

@rest [Parm(In="query", Required=false, Format="pipes")]

Documentation

Index

• Variables
• func ParseType(s string) (*idl.Type, error)
• type Header
• type HttpMethod
  • func (i HttpMethod) String() string
• type ListFmt
  • func (i ListFmt) String() string
• type Operation
  • func ReadOp(mth *idl.Method) (*Operation, error)
• type Parm
  • func ReadParm(fld *idl.Field) (*Parm, error)
• type ParmIn
  • func (i ParmIn) String() string
• type Response

Variables

var (
	ErrMutlipleOps             = errors.New("Only one Op attribute is allowed per method.")
	ErrMutlipleParms           = errors.New("Only one Parm attribute is allowed per method parameter.")
	ErrParmInDataType          = errors.New("Parm.In should be a string with value query, header, path, formData, or body.")
	ErrParmRequiredDataType    = errors.New("Parm.Required should be a bool.")
	ErrParmFormatDataType      = errors.New("Parm.Format should be a string with value csv, ssv, tsv, pipes, or multi.")
	ErrParmNameDataType        = errors.New("Parm.Name should be a string.")
	ErrOpDeprecatedDataType    = errors.New("Op.Deprecated should be a bool.")
	ErrOpHideDataType          = errors.New("Op.Hide should be a bool.")
	ErrOpPathDataType          = errors.New("Op.Path should be a string.")
	ErrOpMethodDataType        = errors.New("Op.Method should be a string with value GET, PUT, POST, DELETE, OPTIONS, HEAD, or PATCH.")
	ErrResponseCodeDataType    = errors.New("Response.Code should be an int.")
	ErrResponseTypeDataType    = errors.New("Response.Type should be a string with a valid Babel type.")
	ErrResponseDescDataType    = errors.New("Response.Desc should be a string.")
	ErrResponseHeadersDataType = errors.New("Response.Headers should be a string containing a comma-separated list of header names.")
	ErrHeaderTypeDataType      = errors.New("Header.Type should be a string with a valid Babel type.")
	ErrHeaderDescDataType      = errors.New("Header.Desc should be a string.")
	ErrHeaderFormatDataType    = errors.New("Header.Format should be a string with value csv, ssv, tsv, pipes, or multi.")
	ErrHeaderNameDataType      = errors.New("Header.Name should be a string.")
	ErrHeaderNameRequired      = errors.New("Header.Name is required.")
	ErrHeaderTypeRequired      = errors.New("Header.Type is required.")
	ErrResponseCodeRequired    = errors.New("Response.Code is required.")
)

Error definitions

Functions

func ParseType

func ParseType(s string) (*idl.Type, error)

ParseType processes a type string and returns the IDL type for it

Types

type Header

type Header struct {
	Type   *idl.Type // Header type
	Desc   string    // Description
	Format ListFmt   // format of list parameters
}

Defines an HTTP header

type HttpMethod

type HttpMethod int

HTTP methods

const (
	GET HttpMethod = iota
	PUT
	POST
	DELETE
	OPTIONS
	HEAD
	PATCH
)

func (HttpMethod) String

func (i HttpMethod) String() string

type ListFmt

type ListFmt int

List format

const (
	NONE  ListFmt = iota // Not applicable
	CSV                  // comma separated values foo,bar
	SSV                  // space separated values foo bar
	TSV                  // tab separated values foo\tbar
	PIPES                // pipe separated values foo|bar
	MULTI                // corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData"
)

func (ListFmt) String

func (i ListFmt) String() string

type Operation

type Operation struct {
	Path       string           // API path
	Method     HttpMethod       // HTTP method
	Deprecated bool             // whether the API is deprecated
	Responses  map[int]Response // Response that can occur
	Hide       bool             // Don't expose this operation from tools
}

Operation defines a RESTful operation

func ReadOp

func ReadOp(mth *idl.Method) (*Operation, error)

ReadOp processes the REST attributes on a method

type Parm

type Parm struct {
	In       ParmIn  // where the parameter comes from
	Required bool    // whether it is required
	Format   ListFmt // format of list parameters
	Name     string  // used to rename (usually for headers)
}

Defines a parameter

func ReadParm

func ReadParm(fld *idl.Field) (*Parm, error)

ReadParm processes the REST attributes on a method parameter

type ParmIn

type ParmIn int

Defines where a parameter is used

const (
	QUERY    ParmIn = iota // query string
	HEADER                 // header
	PATH                   // in the path
	FORMDATA               // form data
	BODY                   // body
)

func (ParmIn) String

func (i ParmIn) String() string

type Response

type Response struct {
	Type    *idl.Type         // Response type
	Headers map[string]Header // Headers that are returned
	Desc    string            // Response description
	// contains filtered or unexported fields
}

Defines a response that can come back from an API