api

Documentation

Overview

Package api contains useful objects and methods to use with APIs.

Index

• Constants
• func NegotiateRequestType(c *gin.Context, supportedTypes map[string]string) (string, error)
• func NegotiateResponseType(c *gin.Context, supportedTypes map[string]string) (string, error)
• func NegotiateVersion(c *gin.Context, handlers VersionedHandlerMap) (gin.HandlerFunc, error)
• func UnversionedJSONObject(vendor, app, object string) string
• func UnversionedObject(vendor, app, object, format string) string
• func VersionedJSONObject(vendor, app, object string, version uint) string
• func VersionedObject(vendor, app, object, format string, version uint) string
• type DeprecatedV1
• type ErrRequestResponseMismatch
  • func (e *ErrRequestResponseMismatch) Code() int
  • func (e *ErrRequestResponseMismatch) Error() string
  • func (e *ErrRequestResponseMismatch) InternalError() error
• type ErrUnsupportedRequestType
  • func (e *ErrUnsupportedRequestType) Code() int
  • func (e *ErrUnsupportedRequestType) Error() string
  • func (e *ErrUnsupportedRequestType) InternalError() error
• type ErrUnsupportedResponseType
  • func (e *ErrUnsupportedResponseType) Code() int
  • func (e *ErrUnsupportedResponseType) Error() string
  • func (e *ErrUnsupportedResponseType) InternalError() error
• type StateV1
  • func StateV1FromData(data map[string]interface{}) StateV1
• type VersionedHandler
• type VersionedHandlerMap
• type VersionedResponseObject

Constants

const (
	ErrUnsupportedRequestTypeCode  = 3001
	ErrUnsupportedResponseTypeCode = 3002
	ErrRequestResponseMismatchCode = 3003
)

Object error codes (3001-3250)

const (
	MimeTypeAny  = "*/*"
	MimeTypeJSON = "application/json"
)

Well-known mime types.

const (
	StateFieldCode           = "code"
	StateFieldDeprecated     = "deprecated"
	StateFieldMimeType       = "mime_type"
	StateFieldMessage        = "message"
	StateFieldPrivateMessage = "private_message"
	StateFieldRequestID      = "request_id"
	StateFieldResult         = "result"
)

State data field names.

const (
	ResultSuccess = "success"
	ResultError   = "error"
	ResultWarning = "warn"
)

Valid values for the "result" field in an API response's state.

Functions

func NegotiateRequestType

func NegotiateRequestType(c *gin.Context, supportedTypes map[string]string) (string, error)

NegotiateRequestType negotiates the type of request object supplied based on the Content-Type header.

A Content-Type header should always be supplied in the request to avoid an error.

The following errors are returned by this function: ErrUnsupportedRequestType

func NegotiateResponseType

func NegotiateResponseType(c *gin.Context, supportedTypes map[string]string) (string, error)

NegotiateResponseType negotiates the type of response object to return based on the Accept header.

An Accept header should always be supplied in the request to avoid an error.

The following errors are returned by this function: ErrUnsupportedResponseType

func NegotiateVersion

func NegotiateVersion(c *gin.Context, handlers VersionedHandlerMap) (gin.HandlerFunc, error)

NegotiateVersion negotiates the versioned request/response objects based on headers.

Content-Type and Accept headers should be supplied in every API request.

The following errors are returned by this function: ErrRequestResponseMismatch, any error from the NegotiateRequestType() or NegotiateResponseType() functions

func UnversionedJSONObject

func UnversionedJSONObject(vendor, app, object string) string

UnversionedJSONObject returns a mime type for an unversioned application-specific JSON object.

func UnversionedObject

func UnversionedObject(vendor, app, object, format string) string

UnversionedObject returns a mime type for an unversioned application-specific object.

func VersionedJSONObject

func VersionedJSONObject(vendor, app, object string, version uint) string

VersionedJSONObject returns a mime type for an versioned application-specific JSON object.

func VersionedObject

func VersionedObject(vendor, app, object, format string, version uint) string

VersionedObject returns a mime type for an versioned application-specfic object.

Types

type DeprecatedV1

type DeprecatedV1 struct {
	// AsOf indicates the date and time when the API call was marked as deprecated.
	AsOf time.Time `json:"as_of"`

	// Message is a user-friendly warning message which can be displayed in a UI.
	Message string `json:"message"`

	// Details holds additional information about the deprecated call that may or may not be friendly for a UI.
	//
	// This field may not always be present in responses.
	Details string `json:"details,omitempty"`
}

DeprecatedV1 holds deprecation information about a particular API call.

type ErrRequestResponseMismatch

type ErrRequestResponseMismatch struct {
	RequestType  string
	ResponseType string
}

ErrRequestResponseMismatch occurs when the negotiated request and response media types are not identical.

func (*ErrRequestResponseMismatch) Code

func (e *ErrRequestResponseMismatch) Code() int

Code returns the corresponding error code.

func (*ErrRequestResponseMismatch) Error

func (e *ErrRequestResponseMismatch) Error() string

Error returns the string version of the error.

func (*ErrRequestResponseMismatch) InternalError

func (e *ErrRequestResponseMismatch) InternalError() error

InternalError returns the internal standard error object if there is one or nil if none is set.

type ErrUnsupportedRequestType

type ErrUnsupportedRequestType struct {
	ContentType    string
	SupportedTypes map[string]string
}

ErrUnsupportedRequestType occurs when the Content-Type header is not a supported media type.

func (*ErrUnsupportedRequestType) Code

func (e *ErrUnsupportedRequestType) Code() int

Code returns the corresponding error code.

func (*ErrUnsupportedRequestType) Error

func (e *ErrUnsupportedRequestType) Error() string

Error returns the string version of the error.

func (*ErrUnsupportedRequestType) InternalError

func (e *ErrUnsupportedRequestType) InternalError() error

InternalError returns the internal standard error object if there is one or nil if none is set.

type ErrUnsupportedResponseType

type ErrUnsupportedResponseType struct {
	Accept         string
	SupportedTypes map[string]string
}

ErrUnsupportedResponseType occurs when the Accept header contains no supported media types.

func (*ErrUnsupportedResponseType) Code

func (e *ErrUnsupportedResponseType) Code() int

Code returns the corresponding error code.

func (*ErrUnsupportedResponseType) Error

func (e *ErrUnsupportedResponseType) Error() string

Error returns the string version of the error.

func (*ErrUnsupportedResponseType) InternalError

func (e *ErrUnsupportedResponseType) InternalError() error

InternalError returns the internal standard error object if there is one or nil if none is set.

type StateV1

type StateV1 struct {
	// Code refers to a status code indicating the return result from the API call.
	Code int `json:"code"`

	// Deprecation information
	//
	// This field may not always be present in responses.
	Deprecated *DeprecatedV1 `json:"deprecated,omitempty"`

	// MimeType indicates the type of object being returned by the API call.
	MimeType string `json:"mime_type"`

	// Message will be any message associated with the API call.
	//
	// This message is safe to display to an end user in a UI.
	Message string `json:"message"`

	// PrivateMessage will be any internal messages associated with the API call.
	//
	// This message is considered internal and should not be displayed in a UI but may be logged for informational
	// purposes.
	//
	//This field may not always be present in responses.
	PrivateMessage string `json:"private_message,omitempty"`

	// RequestID holds a unique request ID associated with the API call, so it can be used in tracing messages.
	RequestID string `json:"request_id"`

	// Result will be a pre-defined status from the list: success, error or warn
	Result string `json:"result"`
}

StateV1 holds response state information returned by the

func StateV1FromData

func StateV1FromData(data map[string]interface{}) StateV1

StateV1FromData extracts and returns a StateV1 object from the arbitrary data passed to the function.

type VersionedHandler

type VersionedHandler struct {
	MimeTypeAliases []string
	Handler         gin.HandlerFunc
}

VersionedHandler is used to store a list of mime types which map to a particular handler.

type VersionedHandlerMap

type VersionedHandlerMap map[string]VersionedHandler

VersionedHandlerMap is used to map a specific mime type to a particular handler.

Additional aliases for the mime type should be specified using the VersionHandler object. For example, if the same handler should be used for application/json requests, add the application/json alias to the VersionedHandler object.

type VersionedResponseObject

type VersionedResponseObject interface {
	Render(map[string]interface{})
}

VersionedResponseObject is an interface describing an object that can be used to render a response.