Skip to main content

Validate

Check every endpoint group against the rules of a definition.

It prints each problem with its group, method, rule and message, then the fix of each rule, and exits 1 when a rule fails. osapi controller endpoint spec get describes each part of a group.

The rules:

  • name: The group and each method have a name of lowercase letters and digits, starting with a letter. Fix: Name the group as its path segment, such as agent, and each method for what it does, such as list or drain.
  • methods: The group has at least one method. Fix: Add a method with endpoint.Get, Post, Put or Delete.
  • unique: No two methods of a group have one name. Fix: Give each method its own name.
  • segment: Each Sub and Action segment is lowercase letters and digits. Fix: Use one word, such as pending or drain.
  • action: A method with an Action has a key: an input field tagged in:"path". Fix: Tag the field the action is on in:"path", or use Sub for a fixed path.
  • key: An input has at most one field tagged in:"path". Fix: Tag one field in:"path"; a group has one key.
  • id: Each operationId is used once, and starts with a capital letter, as each operationId of the API does. Fix: Give the method its own ID with .ID, in Pascal case, such as GetAgents.
  • route: No two methods have one verb and path. Fix: Change the verb, the Sub or the Action.
  • handler: A group that Uses a type gives each method a handler, func(context.Context, D, In) (Out, error), with D that type and In and Out the method's types. A group with a handler Uses a type. Fix: Add .Handle(fn) to each method, with the signature that the message names, and endpoint.Uses[Deps]() to Define.
  • subdoc: Each Sub segment that makes a command of its own, such as trace in osapi client telemetry trace get, has a SubDoc: the one line of help of that command. Fix: Add endpoint.SubDoc("segment", "...") to Define, with what the segment's commands do, such as Read a trace from the tracing backend.
  • validate: Each input field has a validate tag: its rules, or omitempty for an optional field with none. The spec carries the whole tag, and the server answers 400 to a value that breaks it. Fix: Add validate:"..." to the field, such as validate:"required,min=1,max=255", or validate:"omitempty" for an optional field with no other rule.
  • fails: Each rule of an input field has a .Fails input that breaks it, which the API refuses with 400. An endpoint's required needs one, with the field empty; a behavior's needs none, as its generated tests leave the field out. A path field's required, and a min of 1 on a string that is required, optional or in the path, need none: their only bad value is empty. Fix: Add .Fails("<what is wrong>", <Input>{...}) to the method, with the other fields valid and the field's value breaking the rule that the message names, such as a name of 256 characters for max=255.
  • optional: An optional field of a write's request body, with omitempty in its validate tag, has omitempty in its json tag too, so a client leaves it out when it is empty instead of sending "" or 0, which its other rules can refuse. Fix: Add ,omitempty to the field's json tag, such as json:"reason,omitempty".
  • schema: The spec builds: each input and output type is one that JSON can encode, and each validate rule has a schema. Fix: Use structs, slices, maps, strings, numbers, bools and time.Time; not channels or functions. Register the schema of a custom validate rule with rule.Register, beside its validator in internal/validation.
osapi controller endpoint validate

Examples​

osapi controller endpoint validate
osapi controller endpoint validate --json

Global flags​

FlagDescriptionDefault
-d, --debugEnable or disable debug mode
-j, --jsonEnable JSON output
-f, --osapi-filePath to config file/etc/osapi/osapi.yaml

Output tells how the result is printed, and what --json gives.