Kuadrant API Conventions¶
This document outlines a none exhaustive set of conventions that should be used when defining Kuadrant APIs. It is initially focused around the concept of a policy API as these make up the bulk of our public facing APIs. It is expected that this set of conventions will grow as needed overtime.
General rule of thumb¶
If in doubt, first check if a similar API or field exists in the Gateway API spec and re-use that definition to specify what you need in your API. If you need to differ, ensure you explain why in any RFC or PR.
Below are some common examples of these fields and specifications:
Policy Attachment APIs¶
Policy APIs must follow the specification laid out by the Gateway API policy attachment designs. First step is to understand if you are going to design or are working on a direct or inherited policy. The linked docs will help with this but if unsure reach out on github or slack.
Within the linked docs are set of requirements for each type of policy:
Beyond the set of requirement outlined in these specifications, Kuadrant has an additional set of conventions that are used in order to try and ensure our APIs remain consistent and familiar for users of the Gateway API. Most if not all of these come directly from looking at Gateway API.
API Fields and Types¶
Durations
A duration is a field expressing something that configures behaviour that should happen according to a specified duration of time. Examples of this include but are not limited to:
- RateLimit counter expiry
- HealthCheck interval (how often to do the check)
Any API field that expresses this type of time bound behaviour should use a type of time.Duration allowing the duration to be specified in a single field and must match ^([0-9]{1,5}(h|m|s|ms)){1,4}$:
Examples:
20ms,20s,20m,20h
field names for this type of configuration are left up to the designer of the API as they are often specific to the task at hand: IE with a health check it is called an interval within a limit it is called a duration for the timeout filter in HTTPRoute it is called request and backendRequest
hostname | hostnames
When asking for a hostname the field in the API should be named hostname rather than other options such as host, domain etc. The type used for this should be a string or an alias to a string. The plural of this for an array should be hostnames. This also aligns with how the Gateway API specifies these fields. where possible re-use the Gateway API types:
protocol
If there is a need to specify a protocol in the API the field for asking for this should be named: protocol and should accept a string or an alias to a string where possible use ProtocolType provided by Gateway API
port
If there is a need to specify a port in the API, the field should be named port and should accept an int32 with a min of 1 and a max of 65535. Where possible use PortNumberType provided by Gateway API
status
For more information on status please refer to