model

Documentation

Overview

Adding Models

Each model is kept in the model package of the REST v2 API in its own file. To create a new model, define a struct containing all of the fields that it will return and implement its two main interface methods BuildFromService and ToService. Be sure to include struct tags to the define the names the fields will have when serialized to JSON.

Guidlines for Creating Models

Include as much data as a user is likely to want when inspecting this resource. This is likely to be more information than seems directly needed, but there is little penalty to its inclusion.

Use APIString instead of Golang's string type. APIString serializes empty strings as JSON null instead of Go's zero type of '""'.

Use APITime instead of go's time type. APITime is a type that wraps Go's time.Time and automatically and correctly serializes it to ISO-8601 UTC time.

Return an error when type casting fails.

Model Methods

The Model type is an interface with two methods.

BuildFromService(in interface{}) error

BuildFromService fetches all needed data from the passed in object and sets them on the model. BuildFromService may sometimes be called multiple times with different types that all contain data to build up the model object. In this case, a type switch is likely necessary to determine what has been passed in.

ToService()(interface{}, error)

ToService creates an as-complete-as-possible version of the service layer's version of this model. For example, if this is is a REST v2 Task model, the ToService method creates a service layer Task and sets all of the fields it is able to and returns it.

Index

• Constants
• type APIHost
  • func (apiHost *APIHost) BuildFromService(h interface{}) error
  • func (apiHost *APIHost) ToService() (interface{}, error)
• type APIString
  • func (as *APIString) MarshalJSON() ([]byte, error)
  • func (as *APIString) UnmarshalJSON(data []byte) error
• type APITask
  • func (at *APITask) BuildFromService(t interface{}) error
  • func (ad *APITask) ToService() (interface{}, error)
• type APITest
  • func (at *APITest) BuildFromService(st interface{}) error
  • func (at *APITest) ToService() (interface{}, error)
• type APITime
  • func NewTime(t time.Time) APITime
  • func (at APITime) MarshalJSON() ([]byte, error)
  • func (at APITime) String() string
  • func (at *APITime) UnmarshalJSON(b []byte) error
• type MockModel
  • func (m *MockModel) BuildFromService(in interface{}) error
  • func (m *MockModel) ToService() (interface{}, error)
• type MockSubStruct
• type Model
• type TestLogs

Constants

const (
	// This string defines ISO-8601 UTC with 3 fractional seconds behind a dot
	// specified by the API spec document.
	APITimeFormat = "\"2006-01-02T15:04:05.000Z\""
)

const (
	LogLinkFormat = "%s/task_log_raw/%s/%d?type=%s"
)

Types

type APIHost

type APIHost struct {
	Id          APIString  `json:"host_id"`
	Distro      distroInfo `json:"distro"`
	Provisioned bool       `json:"provisioned"`
	StartedBy   APIString  `json:"started_by"`
	Type        APIString  `json:"host_type"`
	User        APIString  `json:"user"`
	Status      APIString  `json:"status"`
	RunningTask taskInfo   `json:"running_task"`
}

APIHost is the model to be returned by the API whenever hosts are fetched.

func (*APIHost) BuildFromService

func (apiHost *APIHost) BuildFromService(h interface{}) error

BuildFromService converts from service level structs to an APIHost. It can be called multiple times with different data types, a service layer host and a service layer task, which are each loaded into the data structure.

func (*APIHost) ToService

func (apiHost *APIHost) ToService() (interface{}, error)

ToService returns a service layer host using the data from the APIHost.

type APIString

type APIString string

func (*APIString) MarshalJSON

func (as *APIString) MarshalJSON() ([]byte, error)

func (*APIString) UnmarshalJSON

func (as *APIString) UnmarshalJSON(data []byte) error

type APITask

type APITask struct {
	Id               APIString        `json:"task_id"`
	CreateTime       APITime          `json:"create_time"`
	DispatchTime     APITime          `json:"dispatch_time"`
	PushTime         APITime          `json:"push_time"`
	ScheduledTime    APITime          `json:"scheduled_time"`
	StartTime        APITime          `json:"start_time"`
	FinishTime       APITime          `json:"finish_time"`
	Version          APIString        `json:"version_id"`
	Branch           APIString        `json:"branch"`
	Revision         APIString        `json:"revision"`
	Priority         int64            `json:"priority"`
	Activated        bool             `json:"activated"`
	ActivatedBy      APIString        `json:"activated_by"`
	BuildId          APIString        `json:"build_id"`
	DistroId         APIString        `json:"distro_id"`
	BuildVariant     APIString        `json:"build_variant"`
	DependsOn        []string         `json:"depends_on"`
	DisplayName      APIString        `json:"display_name"`
	HostId           APIString        `json:"host_id"`
	Restarts         int              `json:"restarts"`
	Execution        int              `json:"execution"`
	Order            int              `json:"order"`
	Status           APIString        `json:"status"`
	Details          apiTaskEndDetail `json:"status_details"`
	Logs             logLinks         `json:"logs"`
	TimeTaken        time.Duration    `json:"time_taken_ms"`
	ExpectedDuration time.Duration    `json:"expected_duration_ms"`
}

APITask is the model to be returned by the API whenever tasks are fetched.

func (*APITask) BuildFromService

func (at *APITask) BuildFromService(t interface{}) error

BuildFromService converts from a service level task by loading the data into the appropriate fields of the APITask.

func (*APITask) ToService

func (ad *APITask) ToService() (interface{}, error)

ToService returns a service layer task using the data from the APITask.

type APITest

type APITest struct {
	TaskId    APIString `json:"task_id"`
	Status    APIString `json:"status"`
	TestFile  APIString `json:"test_file"`
	Logs      TestLogs  `json:"logs"`
	ExitCode  int       `json:"exit_code"`
	StartTime APITime   `json:"start_time"`
	EndTime   APITime   `json:"end_time"`
}

APITest contains the data to be returned whenever a test is used in the API.

func (*APITest) BuildFromService

func (at *APITest) BuildFromService(st interface{}) error

func (*APITest) ToService

func (at *APITest) ToService() (interface{}, error)

type APITime

type APITime time.Time

func NewTime

func NewTime(t time.Time) APITime

NewTime creates a new APITime from an existing time.Time. It handles changing converting from the times time zone to UTC.

func (APITime) MarshalJSON

func (at APITime) MarshalJSON() ([]byte, error)

MarshalJSON implements the custom marshalling of this type so that it can be correctly written out in an API response.

func (APITime) String

func (at APITime) String() string

func (*APITime) UnmarshalJSON

func (at *APITime) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the custom unmarshalling of this type so that it can be correctly parsed from an API request.

type MockModel

type MockModel struct {
	FieldId   string
	FieldInt1 int
	FieldInt2 int
	FieldMap  map[string]string

	FieldStruct *MockSubStruct
}

func (*MockModel) BuildFromService

func (m *MockModel) BuildFromService(in interface{}) error

func (*MockModel) ToService

func (m *MockModel) ToService() (interface{}, error)

type MockSubStruct

type MockSubStruct struct {
	SubInt int
}

type Model

type Model interface {
	BuildFromService(interface{}) error
	ToService() (interface{}, error)
}

Model defines how an API resource which will be both taken from requests and turned into service layer models and taken from service layer models and turned into api models to be returned.

type TestLogs

type TestLogs struct {
	URL     APIString `json:"url"`
	LineNum int       `json:"line_num"`
	URLRaw  APIString `json:"url_raw"`
	LogId   APIString `json:"log_id"`
}

TestLogs is a struct for storing the information about logs that will be written out as part of an APITest.