README
¶
API Versioning
We now make the commitment to users that existing endpoints will not change, either in schema/format or in content (for example, silently changing a branch name field to a SHA).
Any changed endpoints must be put into a separate API version.
This API package allows a developer to create a new API version by defining a new struct
in a new file in this package (api_vX.go) supporting the new routes it defines.
The API version struct is required to have a single method: register(m *mux.Router) which
accepts a Gorilla Mux router. It must define the various routes it implements along with their respective handler methods.
DO NOT serialize or deserialize fundamental data structures in handlers (anything in models.go).
Fundamental data types are subject to change at any time and in that event will break your API, often silently.
Instead, define endpoint input/output structs as private types (ex: apiV2_Environment)
and then provide methods to convert to and from the fundamental types. If anyone changes
the fundamental types that break your API it will likely become a compile time error. Please create unit tests that verify endpoint conformance to your API contracts for better protection against silent breakage.
HOWTO
- Create a new files in this package (
api_v9.go,api_v9_test.go). - Implement a non-exported struct and constructor. The constructor should take all required dependencies as parameters.
- Implement the struct method
register()and register all relevant endpoint routes using the Mux API. - Implement all handler methods.
- Write tests
- Wire in your structs creation and registration in
Dispatcher.RegisterVersions() - Add a line to CHANGELOG describing the API changes and the new version number.
Documentation
¶
Index ¶
- Variables
- type Dependencies
- type Dispatcher
- type ErrorResponseConfig
- type ErrorResponseOption
- type Manager
- type RegisterOption
- func WithAPIKeys(keys []string) RegisterOption
- func WithDebugEndpoints() RegisterOption
- func WithIPWhitelist(ips []string) RegisterOption
- func WithUIAssetsPath(assetsPath string) RegisterOption
- func WithUIBaseURL(baseURL string) RegisterOption
- func WithUIBranding(branding config.UIBrandingConfig) RegisterOption
- func WithUIReload() RegisterOption
- func WithUIRoutePrefix(routePrefix string) RegisterOption
- type StatusTemplateData
- type V2EventStatusSummary
- type V2EventStatusSummaryConfig
- type V2EventStatusTreeNode
- type V2EventStatusTreeNodeChart
- type V2EventStatusTreeNodeImage
- type V2RenderedEventStatus
Constants ¶
This section is empty.
Variables ¶
var MaxAsyncActionTimeout = 32 * time.Minute
MaxAsyncActionTimeout is the maximum amount of time an asynchronous action can take before it's forcibly cancelled This is mainly a failsafe against leaking goroutines, additional more strict timeout logic is implemented by environment operations code. If this timeout occurs, no notifications will be sent to the user.
Functions ¶
This section is empty.
Types ¶
type Dependencies ¶
type Dependencies struct {
DataLayer persistence.DataLayer
GitHubEventWebhook *ghevent.GitHubEventWebhook
EnvironmentSpawner spawner.EnvironmentSpawner
ServerConfig config.ServerConfig
DatadogServiceName string
Logger *log.Logger
}
Dependencies are the dependencies required for the API
type Dispatcher ¶
type Dispatcher struct {
// contains filtered or unexported fields
}
Dispatcher is the concrete implementation of Manager
func NewDispatcher ¶
func NewDispatcher(s *http.Server) *Dispatcher
NewDispatcher returns an initialized Dispatcher. s should be preconfigured to be able to run ListenAndServeTLS()
func (*Dispatcher) RegisterVersions ¶
func (d *Dispatcher) RegisterVersions(deps *Dependencies, ro ...RegisterOption) error
RegisterVersions registers all API versions with the supplied http.Server
func (*Dispatcher) WaitForAsync ¶
func (d *Dispatcher) WaitForAsync()
WaitAsync waits for any async goroutines to finish
func (*Dispatcher) WaitForHandlers ¶
func (d *Dispatcher) WaitForHandlers()
WaitHandlers waits for any handlers that have used waitMiddleware to finish
type ErrorResponseConfig ¶ added in v0.7.0
type ErrorResponseOption ¶ added in v0.7.0
type ErrorResponseOption func(*ErrorResponseConfig)
type Manager ¶
type Manager interface {
RegisterVersions(deps *Dependencies)
Wait()
}
Manager describes an object capable of registering API versions and waiting on requests
type RegisterOption ¶
type RegisterOption func(*registerOptions)
RegisterOption is an option for RegisterVersions()
func WithAPIKeys ¶
func WithAPIKeys(keys []string) RegisterOption
WithAPIKeys supplies API keys for protected endpoints
func WithDebugEndpoints ¶
func WithDebugEndpoints() RegisterOption
WithDebugEndpoints causes RegisterVersions to register debug pprof endpoints
func WithIPWhitelist ¶
func WithIPWhitelist(ips []string) RegisterOption
WithIPWhitelist supplies IP CIDRs for whitelisted endpoints. Invalid CIDRs are ignored.
func WithUIAssetsPath ¶ added in v0.7.5
func WithUIAssetsPath(assetsPath string) RegisterOption
func WithUIBaseURL ¶ added in v0.7.5
func WithUIBaseURL(baseURL string) RegisterOption
func WithUIBranding ¶ added in v0.7.5
func WithUIBranding(branding config.UIBrandingConfig) RegisterOption
func WithUIReload ¶ added in v0.7.5
func WithUIReload() RegisterOption
func WithUIRoutePrefix ¶ added in v0.7.5
func WithUIRoutePrefix(routePrefix string) RegisterOption
type StatusTemplateData ¶ added in v0.7.5
type V2EventStatusSummary ¶ added in v0.7.5
type V2EventStatusSummary struct {
Config V2EventStatusSummaryConfig `json:"config"`
Tree map[string]V2EventStatusTreeNode `json:"tree"`
}
func V2EventStatusSummaryFromEventStatusSummary ¶ added in v0.7.5
func V2EventStatusSummaryFromEventStatusSummary(sum *models.EventStatusSummary) *V2EventStatusSummary
type V2EventStatusSummaryConfig ¶ added in v0.7.5
type V2EventStatusSummaryConfig struct {
Type string `json:"type"`
Status string `json:"status"`
RenderedStatus V2RenderedEventStatus `json:"rendered_status"`
EnvName string `json:"env_name"`
K8sNamespace string `json:"k8s_ns"`
TriggeringRepo string `json:"triggering_repo"`
PullRequest uint `json:"pull_request"`
GitHubUser string `json:"github_user"`
Branch string `json:"branch"`
Revision string `json:"revision"`
ProcessingTime string `json:"processing_time"`
Started *time.Time `json:"started"`
Completed *time.Time `json:"completed"`
RefMap map[string]string `json:"ref_map"`
}
type V2EventStatusTreeNode ¶ added in v0.7.5
type V2EventStatusTreeNode struct {
Parent string `json:"parent"`
Image *V2EventStatusTreeNodeImage `json:"image"`
Chart V2EventStatusTreeNodeChart `json:"chart"`
}
type V2EventStatusTreeNodeChart ¶ added in v0.7.5
type V2EventStatusTreeNodeImage ¶ added in v0.7.5
type V2RenderedEventStatus ¶ added in v0.7.5
type V2RenderedEventStatus struct {
Description string `json:"description"`
LinkTargetURL string `json:"link_target_url"`
}
func V2RenderedStatusFromRenderedStatus ¶ added in v0.7.5
func V2RenderedStatusFromRenderedStatus(rs models.RenderedEventStatus) V2RenderedEventStatus
Source Files