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 ¶
Constants ¶
This section is empty.
Variables ¶
var MaxAsyncActionTimeout = 30 * time.Minute
MaxAsyncActionTimeout is the maximum amount of time an asynchronous action can take before it's forcibly cancelled
Functions ¶
This section is empty.
Types ¶
type Dependencies ¶
type Dependencies struct {
DataLayer persistence.DataLayer
GitHubEventWebhook *ghevent.GitHubEventWebhook
EnvironmentSpawner spawner.EnvironmentSpawner
ServerConfig config.ServerConfig
NRApplication newrelic.Application
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 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.
Source Files