Corrections on the api spec. (#81)

* Corrections on the api spec.

* Resolving spec errors.

* All search query params are optional.

* More corrections.

* Do not mention version in spec.

Makefile

@@ -1,6 +1,7 @@
 BINARY := metal-api
 MAINMODULE := github.com/metal-stack/metal-api/cmd/metal-api
 COMMONDIR := $(or ${COMMONDIR},../builder)
+MINI_LAB_KUBECONFIG := $(shell pwd)/../mini-lab/.kubeconfig
 
 include $(COMMONDIR)/Makefile.inc
 
@@ -22,3 +23,10 @@ protoc:
 .PHONY: protoc-docker
 protoc-docker:
 	docker run --rm --user $$(id -u):$$(id -g) -v $(PWD):/work -w /work metalstack/builder protoc -I pkg --go_out plugins=grpc:pkg pkg/api/v1/*.proto
+
+.PHONY: mini-lab-push
+mini-lab-push:
+	docker build -t metalstack/metal-api:latest .
+	kind --name metal-control-plane load docker-image metalstack/metal-api:latest
+	kubectl --kubeconfig=$(MINI_LAB_KUBECONFIG) patch deployments.apps -n metal-control-plane metal-api --patch='{"spec":{"template":{"spec":{"containers":[{"name": "metal-api","imagePullPolicy":"IfNotPresent","image":"metalstack/metal-api:latest"}]}}}}'
+	kubectl --kubeconfig=$(MINI_LAB_KUBECONFIG) delete pod -n metal-control-plane -l app=metal-api

cmd/metal-api/internal/datastore/ip.go

@@ -8,13 +8,13 @@ import (
 
 // IPSearchQuery can be used to search networks.
 type IPSearchQuery struct {
-	IPAddress        *string  `json:"ipaddress" modelDescription:"an ip address that can be attached to a machine" description:"the address (ipv4 or ipv6) of this ip"`
-	ParentPrefixCidr *string  `json:"networkprefix" description:"the prefix of the network this ip address belongs to"`
-	NetworkID        *string  `json:"networkid" description:"the network this ip allocate request address belongs to"`
-	Tags             []string `json:"tags" description:"the tags that are assigned to this ip address"`
-	ProjectID        *string  `json:"projectid" description:"the project this ip address belongs to, empty if not strong coupled"`
-	Type             *string  `json:"type" description:"the type of the ip address, ephemeral or static"`
-	MachineID        *string  `json:"machineid" description:"the machine an ip address is associated to"`
+	IPAddress        *string  `json:"ipaddress" modelDescription:"an ip address that can be attached to a machine" description:"the address (ipv4 or ipv6) of this ip" optional:"true"`
+	ParentPrefixCidr *string  `json:"networkprefix" description:"the prefix of the network this ip address belongs to" optional:"true"`
+	NetworkID        *string  `json:"networkid" description:"the network this ip allocate request address belongs to" optional:"true"`
+	Tags             []string `json:"tags" description:"the tags that are assigned to this ip address" optional:"true"`
+	ProjectID        *string  `json:"projectid" description:"the project this ip address belongs to, empty if not strong coupled" optional:"true"`
+	Type             *string  `json:"type" description:"the type of the ip address, ephemeral or static" optional:"true"`
+	MachineID        *string  `json:"machineid" description:"the machine an ip address is associated to" optional:"true"`
 }
 
 // GenerateTerm generates the project search query term.

cmd/metal-api/internal/datastore/machine.go

@@ -9,66 +9,66 @@ import (
 
 // MachineSearchQuery can be used to search machines.
 type MachineSearchQuery struct {
-	ID          *string  `json:"id"`
-	Name        *string  `json:"name"`
-	PartitionID *string  `json:"partition_id"`
-	SizeID      *string  `json:"sizeid"`
-	RackID      *string  `json:"rackid"`
-	Liveliness  *string  `json:"liveliness"`
-	Tags        []string `json:"tags"`
+	ID          *string  `json:"id" optional:"true"`
+	Name        *string  `json:"name" optional:"true"`
+	PartitionID *string  `json:"partition_id" optional:"true"`
+	SizeID      *string  `json:"sizeid" optional:"true"`
+	RackID      *string  `json:"rackid" optional:"true"`
+	Liveliness  *string  `json:"liveliness" optional:"true"`
+	Tags        []string `json:"tags" optional:"true"`
 
 	// allocation
-	AllocationName      *string `json:"allocation_name"`
-	AllocationProject   *string `json:"allocation_project"`
-	AllocationImageID   *string `json:"allocation_image_id"`
-	AllocationHostname  *string `json:"allocation_hostname"`
-	AllocationSucceeded *bool   `json:"allocation_succeeded"`
+	AllocationName      *string `json:"allocation_name" optional:"true"`
+	AllocationProject   *string `json:"allocation_project" optional:"true"`
+	AllocationImageID   *string `json:"allocation_image_id" optional:"true"`
+	AllocationHostname  *string `json:"allocation_hostname" optional:"true"`
+	AllocationSucceeded *bool   `json:"allocation_succeeded" optional:"true"`
 
 	// network
-	NetworkIDs                 []string `json:"network_ids"`
-	NetworkPrefixes            []string `json:"network_prefixes"`
-	NetworkIPs                 []string `json:"network_ips"`
-	NetworkDestinationPrefixes []string `json:"network_destination_prefixes"`
-	NetworkVrfs                []int64  `json:"network_vrfs"`
-	NetworkPrivate             *bool    `json:"network_private"`
-	NetworkASNs                []int64  `json:"network_asns"`
-	NetworkNat                 *bool    `json:"network_nat"`
-	NetworkUnderlay            *bool    `json:"network_underlay"`
+	NetworkIDs                 []string `json:"network_ids" optional:"true"`
+	NetworkPrefixes            []string `json:"network_prefixes" optional:"true"`
+	NetworkIPs                 []string `json:"network_ips" optional:"true"`
+	NetworkDestinationPrefixes []string `json:"network_destination_prefixes" optional:"true"`
+	NetworkVrfs                []int64  `json:"network_vrfs" optional:"true"`
+	NetworkPrivate             *bool    `json:"network_private" optional:"true"`
+	NetworkASNs                []int64  `json:"network_asns" optional:"true"`
+	NetworkNat                 *bool    `json:"network_nat" optional:"true"`
+	NetworkUnderlay            *bool    `json:"network_underlay" optional:"true"`
 
 	// hardware
-	HardwareMemory   *int64 `json:"hardware_memory"`
-	HardwareCPUCores *int64 `json:"hardware_cpu_cores"`
+	HardwareMemory   *int64 `json:"hardware_memory" optional:"true"`
+	HardwareCPUCores *int64 `json:"hardware_cpu_cores" optional:"true"`
 
 	// nics
-	NicsMacAddresses         []string `json:"nics_mac_addresses"`
-	NicsNames                []string `json:"nics_names"`
-	NicsVrfs                 []string `json:"nics_vrfs"`
-	NicsNeighborMacAddresses []string `json:"nics_neighbor_mac_addresses"`
-	NicsNeighborNames        []string `json:"nics_neighbor_names"`
-	NicsNeighborVrfs         []string `json:"nics_neighbor_vrfs"`
+	NicsMacAddresses         []string `json:"nics_mac_addresses" optional:"true"`
+	NicsNames                []string `json:"nics_names" optional:"true"`
+	NicsVrfs                 []string `json:"nics_vrfs" optional:"true"`
+	NicsNeighborMacAddresses []string `json:"nics_neighbor_mac_addresses" optional:"true"`
+	NicsNeighborNames        []string `json:"nics_neighbor_names" optional:"true"`
+	NicsNeighborVrfs         []string `json:"nics_neighbor_vrfs" optional:"true"`
 
 	// disks
-	DiskNames []string `json:"disk_names"`
-	DiskSizes []int64  `json:"disk_sizes"`
+	DiskNames []string `json:"disk_names" optional:"true"`
+	DiskSizes []int64  `json:"disk_sizes" optional:"true"`
 
 	// state
-	StateValue *string `json:"state_value"`
+	StateValue *string `json:"state_value" optional:"true"`
 
 	// ipmi
-	IpmiAddress    *string `json:"ipmi_address"`
-	IpmiMacAddress *string `json:"ipmi_mac_address"`
-	IpmiUser       *string `json:"ipmi_user"`
-	IpmiInterface  *string `json:"ipmi_interface"`
+	IpmiAddress    *string `json:"ipmi_address" optional:"true"`
+	IpmiMacAddress *string `json:"ipmi_mac_address" optional:"true"`
+	IpmiUser       *string `json:"ipmi_user" optional:"true"`
+	IpmiInterface  *string `json:"ipmi_interface" optional:"true"`
 
 	// fru
-	FruChassisPartNumber   *string `json:"fru_chassis_part_number"`
-	FruChassisPartSerial   *string `json:"fru_chassis_part_serial"`
-	FruBoardMfg            *string `json:"fru_board_mfg"`
-	FruBoardMfgSerial      *string `json:"fru_board_mfg_serial"`
-	FruBoardPartNumber     *string `json:"fru_board_part_number"`
-	FruProductManufacturer *string `json:"fru_product_manufacturer"`
-	FruProductPartNumber   *string `json:"fru_product_part_number"`
-	FruProductSerial       *string `json:"fru_product_serial"`
+	FruChassisPartNumber   *string `json:"fru_chassis_part_number" optional:"true"`
+	FruChassisPartSerial   *string `json:"fru_chassis_part_serial" optional:"true"`
+	FruBoardMfg            *string `json:"fru_board_mfg" optional:"true"`
+	FruBoardMfgSerial      *string `json:"fru_board_mfg_serial" optional:"true"`
+	FruBoardPartNumber     *string `json:"fru_board_part_number" optional:"true"`
+	FruProductManufacturer *string `json:"fru_product_manufacturer" optional:"true"`
+	FruProductPartNumber   *string `json:"fru_product_part_number" optional:"true"`
+	FruProductSerial       *string `json:"fru_product_serial" optional:"true"`
 }
 
 // GenerateTerm generates the project search query term.

cmd/metal-api/internal/datastore/network.go

@@ -10,18 +10,18 @@ import (
 
 // NetworkSearchQuery can be used to search networks.
 type NetworkSearchQuery struct {
-	ID                  *string           `json:"id"`
-	Name                *string           `json:"name"`
-	PartitionID         *string           `json:"partitionid"`
-	ProjectID           *string           `json:"projectid"`
-	Prefixes            []string          `json:"prefixes"`
-	DestinationPrefixes []string          `json:"destinationprefixes"`
-	Nat                 *bool             `json:"nat"`
-	PrivateSuper        *bool             `json:"privatesuper"`
-	Underlay            *bool             `json:"underlay"`
-	Vrf                 *int64            `json:"vrf"`
-	ParentNetworkID     *string           `json:"parentnetworkid"`
-	Labels              map[string]string `json:"labels"`
+	ID                  *string           `json:"id" optional:"true"`
+	Name                *string           `json:"name" optional:"true"`
+	PartitionID         *string           `json:"partitionid" optional:"true"`
+	ProjectID           *string           `json:"projectid" optional:"true"`
+	Prefixes            []string          `json:"prefixes" optional:"true"`
+	DestinationPrefixes []string          `json:"destinationprefixes" optional:"true"`
+	Nat                 *bool             `json:"nat" optional:"true"`
+	PrivateSuper        *bool             `json:"privatesuper" optional:"true"`
+	Underlay            *bool             `json:"underlay" optional:"true"`
+	Vrf                 *int64            `json:"vrf" optional:"true"`
+	ParentNetworkID     *string           `json:"parentnetworkid" optional:"true"`
+	Labels              map[string]string `json:"labels" optional:"true"`
 }
 
 // GenerateTerm generates the project search query term.

cmd/metal-api/internal/service/machine-service.go

@@ -344,28 +344,18 @@ func (r machineResource) webService() *restful.WebService {
 		Operation("chassisIdentifyLEDOn").
 		Doc("sends a power-on to the chassis identify LED").
 		Param(ws.PathParameter("id", "identifier of the machine").DataType("string")).
+		Param(ws.QueryParameter("description", "identifier of the machine").DataType("string")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Reads(v1.EmptyBody{}).
 		Returns(http.StatusOK, "OK", v1.MachineResponse{}).
 		DefaultReturns("Error", httperrors.HTTPErrorResponse{}))
 
-	ws.Route(ws.POST("/{id}/power/chassis-identify-led-on/{description}").
-		To(editor(r.chassisIdentifyLEDOn)).
-		Operation("chassisIdentifyLEDOn").
-		Doc("sends a power-on to the chassis identify LED").
-		Param(ws.PathParameter("id", "identifier of the machine").DataType("string")).
-		Param(ws.PathParameter("description", "reason why the chassis identify LED has been turned on").DataType("string")).
-		Metadata(restfulspec.KeyOpenAPITags, tags).
-		Reads(v1.EmptyBody{}).
-		Returns(http.StatusOK, "OK", v1.MachineResponse{}).
-		DefaultReturns("Error", httperrors.HTTPErrorResponse{}))
-
-	ws.Route(ws.POST("/{id}/power/chassis-identify-led-off/{description}").
+	ws.Route(ws.POST("/{id}/power/chassis-identify-led-off").
 		To(editor(r.chassisIdentifyLEDOff)).
 		Operation("chassisIdentifyLEDOff").
 		Doc("sends a power-off to the chassis identify LED").
 		Param(ws.PathParameter("id", "identifier of the machine").DataType("string")).
-		Param(ws.PathParameter("description", "reason why the chassis identify LED has been turned off").DataType("string")).
+		Param(ws.QueryParameter("description", "reason why the chassis identify LED has been turned off").DataType("string")).
 		Metadata(restfulspec.KeyOpenAPITags, tags).
 		Reads(v1.EmptyBody{}).
 		Returns(http.StatusOK, "OK", v1.MachineResponse{}).
@@ -1847,11 +1837,11 @@ func (r machineResource) machineBios(request *restful.Request, response *restful
 }
 
 func (r machineResource) chassisIdentifyLEDOn(request *restful.Request, response *restful.Response) {
-	r.machineCmd("chassisIdentifyLEDOn", metal.ChassisIdentifyLEDOnCmd, request, response, request.PathParameter("description"))
+	r.machineCmd("chassisIdentifyLEDOn", metal.ChassisIdentifyLEDOnCmd, request, response, request.QueryParameter("description"))
 }
 
 func (r machineResource) chassisIdentifyLEDOff(request *restful.Request, response *restful.Response) {
-	r.machineCmd("chassisIdentifyLEDOff", metal.ChassisIdentifyLEDOffCmd, request, response, request.PathParameter("description"))
+	r.machineCmd("chassisIdentifyLEDOff", metal.ChassisIdentifyLEDOffCmd, request, response, request.QueryParameter("description"))
 }
 
 func (r machineResource) machineCmd(op string, cmd metal.MachineCommand, request *restful.Request, response *restful.Response, params ...string) {

cmd/metal-api/internal/service/machine-service_test.go

@@ -669,11 +669,11 @@ func TestOnMachine(t *testing.T) {
 		},
 		{
 			cmd:      metal.ChassisIdentifyLEDOnCmd,
-			endpoint: "chassis-identify-led-on/test",
+			endpoint: "chassis-identify-led-on?description=test",
 		},
 		{
 			cmd:      metal.ChassisIdentifyLEDOffCmd,
-			endpoint: "chassis-identify-led-off/test",
+			endpoint: "chassis-identify-led-off?description=test",
 		},
 	}
 

cmd/metal-api/internal/service/v1/common.go

@@ -24,6 +24,6 @@ type Common struct {
 }
 
 type Timestamps struct {
-	Created time.Time `json:"created" description:"the creation time of this entity" readOnly:"true"`
-	Changed time.Time `json:"changed" description:"the last changed timestamp of this entity" readOnly:"true"`
+	Created time.Time `json:"created" description:"the creation time of this entity" readOnly:"true" optional:"true"`
+	Changed time.Time `json:"changed" description:"the last changed timestamp of this entity" readOnly:"true" optional:"true"`
 }

cmd/metal-api/internal/service/v1/ip.go

@@ -9,7 +9,7 @@ type IPBase struct {
 	ProjectID string       `json:"projectid" description:"the project this ip address belongs to"`
 	NetworkID string       `json:"networkid" description:"the network this ip allocate request address belongs to"`
 	Type      metal.IPType `json:"type" default:"static" enum:"static|ephemeral" description:"the ip type, ephemeral leads to automatic cleanup of the ip address, static will enable re-use of the ip at a later point in time"`
-	Tags      []string     `json:"tags" description:"free tags that you associate with this ip."`
+	Tags      []string     `json:"tags" description:"free tags that you associate with this ip." optional:"true"`
 }
 
 type IPIdentifiable struct {
@@ -19,14 +19,14 @@ type IPIdentifiable struct {
 type IPAllocateRequest struct {
 	Describable
 	IPBase
-	MachineID *string `json:"machineid" description:"the machine id this ip should be associated with"`
+	MachineID *string `json:"machineid" description:"the machine id this ip should be associated with" optional:"true"`
 }
 
 type IPUpdateRequest struct {
 	IPIdentifiable
 	Describable
 	Type metal.IPType `json:"type" enum:"static|ephemeral" description:"the ip type, ephemeral leads to automatic cleanup of the ip address, static will enable re-use of the ip at a later point in time"`
-	Tags []string     `json:"tags" description:"free tags that you associate with this ip."`
+	Tags []string     `json:"tags" description:"free tags that you associate with this ip." optional:"true"`
 }
 
 type IPFindRequest struct {
@@ -41,6 +41,10 @@ type IPResponse struct {
 }
 
 func NewIPResponse(ip *metal.IP) *IPResponse {
+	tags := ip.Tags
+	if tags == nil {
+		tags = []string{}
+	}
 	return &IPResponse{
 		Describable: Describable{
 			Name:        &ip.Name,
@@ -50,7 +54,7 @@ func NewIPResponse(ip *metal.IP) *IPResponse {
 			NetworkID: ip.NetworkID,
 			ProjectID: ip.ProjectID,
 			Type:      ip.Type,
-			Tags:      ip.Tags,
+			Tags:      tags,
 		},
 		IPIdentifiable: IPIdentifiable{
 			IPAddress: ip.IPAddress,

cmd/metal-api/internal/service/v1/machine.go

@@ -11,12 +11,12 @@ import (
 const RecentProvisioningEventsLimit = 5
 
 type MachineBase struct {
-	Partition                *PartitionResponse              `json:"partition" modelDescription:"A machine representing a bare metal machine." description:"the partition assigned to this machine" readOnly:"true"`
-	RackID                   string                          `json:"rackid" description:"the rack assigned to this machine" readOnly:"true"`
-	Size                     *SizeResponse                   `json:"size" description:"the size of this machine" readOnly:"true"`
+	Partition                *PartitionResponse              `json:"partition" modelDescription:"A machine representing a bare metal machine." description:"the partition assigned to this machine" readOnly:"true" optional:"true"`
+	RackID                   string                          `json:"rackid" description:"the rack assigned to this machine" readOnly:"true" optional:"true"`
+	Size                     *SizeResponse                   `json:"size" description:"the size of this machine" readOnly:"true" optional:"true"`
 	Hardware                 MachineHardware                 `json:"hardware" description:"the hardware of this machine"`
 	BIOS                     MachineBIOS                     `json:"bios" description:"bios information of this machine"`
-	Allocation               *MachineAllocation              `json:"allocation" description:"the allocation data of an allocated machine"`
+	Allocation               *MachineAllocation              `json:"allocation" description:"the allocation data of an allocated machine" optional:"true"`
 	State                    MachineState                    `json:"state" rethinkdb:"state" description:"the state of this machine"`
 	LEDState                 ChassisIdentifyLEDState         `json:"ledstate" rethinkdb:"ledstate" description:"the state of this chassis identify LED"`
 	Liveliness               string                          `json:"liveliness" description:"the liveliness of this machine"`
@@ -91,7 +91,7 @@ type ChassisIdentifyLEDState struct {
 type MachineBlockDevice struct {
 	Name       string                `json:"name" description:"the name of this block device"`
 	Size       uint64                `json:"size" description:"the size of this block device"`
-	Partitions MachineDiskPartitions `json:"partitions" description:"the partitions of this disk"`
+	Partitions MachineDiskPartitions `json:"partitions" description:"the partitions of this disk" optional:"true"`
 	Primary    bool                  `json:"primary" description:"whether this disk has the OS installed"`
 }
 

cmd/metal-api/internal/service/v1/network.go

@@ -9,7 +9,7 @@ import (
 type NetworkBase struct {
 	PartitionID *string           `json:"partitionid" description:"the partition this network belongs to" optional:"true"`
 	ProjectID   *string           `json:"projectid" description:"the project id this network belongs to, can be empty if globally available" optional:"true"`
-	Labels      map[string]string `json:"labels" description:"free labels that you associate with this network."`
+	Labels      map[string]string `json:"labels" description:"free labels that you associate with this network." optional:"true"`
 }
 
 // NetworkImmutable defines the properties which are immutable in the Network.
@@ -77,6 +77,10 @@ func NewNetworkResponse(network *metal.Network, usage *metal.NetworkUsage) *Netw
 	if network.ParentNetworkID != "" {
 		parentNetworkID = &network.ParentNetworkID
 	}
+	labels := network.Labels
+	if labels == nil {
+		labels = make(map[string]string)
+	}
 
 	return &NetworkResponse{
 		Common: Common{
@@ -91,7 +95,7 @@ func NewNetworkResponse(network *metal.Network, usage *metal.NetworkUsage) *Netw
 		NetworkBase: NetworkBase{
 			PartitionID: &network.PartitionID,
 			ProjectID:   &network.ProjectID,
-			Labels:      network.Labels,
+			Labels:      labels,
 		},
 		NetworkImmutable: NetworkImmutable{
 			Prefixes:            network.Prefixes.String(),