Separate API filter parameters into ID and Filter to improve discovery and validation

[mdbooth]

This applies to all our filter types:

• NetworkFilter
• SubnetFilter
• ImageFilter
• SecurityGroupFilter
• RouterFilter

Taking RouterFilter as an example, we have:

type RouterFilter struct {
    ID          string `json:"id,omitempty"`
    Name        string `json:"name,omitempty"`
    Description string `json:"description,omitempty"`
    ProjectID   string `json:"projectID,omitempty"`

    FilterByNeutronTags `json:",inline"`
}

This struct encode 2 different behaviours:

• If ID is set, all other parameters are ignored and we use the given ID without further validation
• If ID is not set, we use all the remaining parameters to execute an OpenStack query to discover a router to use.

We would like to make this behaviour both obvious to users, and impossible to misuse. To achieve this, we turn the Filter struct into a Param struct which has an ID field and a Filter field. The Filter field no longer includes an ID. Taking the RouterFilter example again, this becomes:

type RouterParam struct {
    ID          optional.String `json:"id,omitempty"`
    Filter     *RouterFilter   `json:"filter,omitempty"`
}

type RouterFilter struct {
    Name        string `json:"name,omitempty"`
    Description string `json:"description,omitempty"`
    ProjectID   string `json:"projectID,omitempty"`

    FilterByNeutronTags `json:",inline"`
}

We now use RouterParam everywhere we formerly used RouterFilter. We also add API validation which ensures that exactly one of ID or Filter must be set so the user will get an immediate admission failure if they attempt to specify an invalid filter.

/type feature