Skip to content

fix(api): HTTP semantics, group config resource, simpler fields, strict lint #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Zakkaus merged 7 commits into from
Sep 28, 2026
Merged

fix(api): HTTP semantics, group config resource, simpler fields, strict lint #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
526b8f1
fix(api): align conditional requests and statuses with the HTTP RFCs
Zakkaus Sep 28, 2026
7169e52
feat(api): conditional group patch on a configuration resource
Zakkaus Sep 28, 2026
f27bd4f
fix(api): drop engine-specific and redundant fields
Zakkaus Sep 28, 2026
acbcbba
chore(lint): tags and recommended-strict Redocly lint
Zakkaus Sep 28, 2026
8a0f837
fix(api): content-only source representation and RFC entity-tag lists
Zakkaus Sep 28, 2026
7946a8d
docs(api): complete examples and create conflict descriptions
Zakkaus Sep 28, 2026
487585c
docs(api): plainer wording for preconditions, recording policy and pr…
Zakkaus Sep 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions .redocly.lint-ignore.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Per-location lint exceptions; redocly.yaml explains each rule listed here.
# Regenerate with: redocly lint source/openapi.yaml --config redocly.yaml --generate-ignore-file
# and review that every new entry is a conditional branch, an SSE binding or the local server.
source/openapi.yaml:
no-server-example.com:
- '#/servers/0/url'
no-required-schema-properties-undefined:
- >-
#/components/schemas/Capabilities/properties/resources/properties/config/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/config/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/config/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/config_validate/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/config_validate/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/config_validate/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/runtime_memory/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/traffic_history/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/traffic_history/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/memory_history/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/memory_history/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/datapath/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/datapath/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/nodes/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/providers/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/providers/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/providers/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/groups/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/groups/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/groups/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/probes/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/probes/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/probes/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/probes/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/probes/then/required/4
- >-
#/components/schemas/Capabilities/properties/resources/properties/connections/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/connections/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/4
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/5
- >-
#/components/schemas/Capabilities/properties/resources/properties/flows/then/required/6
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/4
- >-
#/components/schemas/Capabilities/properties/resources/properties/routing_trace/then/required/5
- >-
#/components/schemas/Capabilities/properties/resources/properties/rules/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/events/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/events/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/events/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/events/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/events/then/required/4
- >-
#/components/schemas/Capabilities/properties/resources/properties/logs/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/logs/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/logs/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/logs/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_query/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_query/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_cache/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_cache/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_cache/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_cache/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_cache/then/required/4
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_log/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_log/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/dns_rules/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/runtime_settings/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/0/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/0/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/1/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/2/then/required/0
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/2/then/required/1
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/2/then/required/2
- >-
#/components/schemas/Capabilities/properties/resources/properties/geodata/allOf/2/then/required/3
- >-
#/components/schemas/Capabilities/properties/resources/properties/operations/then/required/0
- '#/components/schemas/EbpfAttachment/allOf/0/then/required/0'
- '#/components/schemas/EbpfAttachment/allOf/0/then/required/1'
- '#/components/schemas/EbpfAttachment/allOf/1/then/required/0'
- '#/components/schemas/EbpfAttachment/allOf/2/then/required/0'
- '#/components/schemas/ProbeRequest/allOf/0/then/not/required/0'
- '#/components/schemas/FlowDetail/allOf/1/not/required/0'
- '#/components/schemas/RoutingTraceResponse/not/anyOf/0/required/0'
- '#/components/schemas/RoutingTraceResponse/not/anyOf/1/required/0'
- '#/components/schemas/RoutingTraceResponse/not/anyOf/2/required/0'
- '#/components/schemas/GeoDataDownloadPatch/then/required/0'
- '#/components/schemas/GeoDataDownloadPatch/else/not/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/0/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/1/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/2/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/3/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/4/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/5/required/0'
- '#/components/schemas/StreamReadyEvent/not/anyOf/6/required/0'
no-unused-components:
- '#/components/schemas/LogRecord'
- '#/components/schemas/StreamReadyEvent'
- '#/components/schemas/RuntimeUpdatedEvent'
- '#/components/schemas/FlowUpdatedEvent'
- '#/components/schemas/FlowGapEvent'
- '#/components/schemas/OperationUpdatedEvent'
- '#/components/schemas/GenerationChangedEvent'
- '#/components/examples/FlowUpdated'
3 changes: 3 additions & 0 deletions api/auth.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ paths:
/api/v1/auth/setup:
post:
operationId: setupAdministrator
tags: [ Authentication ]
summary: Create the administrator account and open a session
description: >-
Available only while discovery reports `auth.mode: password` with
Expand Down Expand Up @@ -66,6 +67,7 @@ paths:
/api/v1/auth/login:
post:
operationId: login
tags: [ Authentication ]
summary: Exchange the administrator credentials for a session
description: >-
Available only in password mode after setup. Checks run in this order:
Expand Down Expand Up @@ -129,6 +131,7 @@ paths:
/api/v1/auth/logout:
post:
operationId: logout
tags: [ Authentication ]
summary: End the session that authenticates this request
description: Requires a password-session bearer; a configured bearer cannot log out.
security:
Expand Down
51 changes: 24 additions & 27 deletions api/common.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ headers:
type: string
const: nosniff
ETag:
description: Quoted group configuration revision.
description: Strong entity tag of the representation, the value a later If-Match compares.
required: true
schema:
type: string
Expand Down Expand Up @@ -106,9 +106,16 @@ parameters:
name: If-Match
in: header
required: true
description: Evaluated as RFC 9110 §13.1.1 defines; see Conditional requests in the error contract.
schema:
type: string
minLength: 1
$ref: ./openapi.yaml#/components/schemas/EntityTagList
example: '"d1f62f00c6da9ec33956e66b8cc3b4670f164556fc12453193904af23451dec1"'
IfMatchOptional:
name: If-Match
in: header
description: Evaluated as RFC 9110 §13.1.1 defines; see Conditional requests in the error contract. A new group-configuration PATCH without If-Match returns 428 precondition_required; a retained idempotent replay may omit it.
schema:
$ref: ./openapi.yaml#/components/schemas/EntityTagList
example: '"17"'
IdempotencyKey:
name: Idempotency-Key
Expand Down Expand Up @@ -196,6 +203,12 @@ responses:
Unauthorized:
description: Credentials are missing or invalid
headers:
WWW-Authenticate:
description: The authentication challenge (RFC 9110 §15.5.2); the native API uses the Bearer scheme.
required: true
schema:
type: string
pattern: ^Bearer(\s|$)
Cache-Control:
$ref: ./openapi.yaml#/components/headers/NoStore
X-Content-Type-Options:
Expand All @@ -214,6 +227,7 @@ responses:
request_id: request-01HZX4K8W6
x-headers:
Content-Type: application/json
WWW-Authenticate: Bearer
Cache-Control: no-store
X-Content-Type-Options: nosniff
Forbidden:
Expand Down Expand Up @@ -322,29 +336,6 @@ responses:
Content-Type: application/json
Cache-Control: no-store
X-Content-Type-Options: nosniff
PreconditionFailed:
description: If-Match does not equal the current configuration revision or stored source content hash
headers:
Cache-Control:
$ref: ./openapi.yaml#/components/headers/NoStore
X-Content-Type-Options:
$ref: ./openapi.yaml#/components/headers/NoSniff
content:
application/json:
schema:
$ref: ./openapi.yaml#/components/schemas/ErrorResponse
examples:
stale_revision:
value:
error:
code: stale_revision
message: The resource changed; read it again.
details: null
request_id: request-01HZX4K8W6
x-headers:
Content-Type: application/json
Cache-Control: no-store
X-Content-Type-Options: nosniff
TooLarge:
description: Request size or advertised fan-out limit exceeded
headers:
Expand Down Expand Up @@ -548,6 +539,7 @@ schemas:
- permission_denied
- resource_not_found
- capability_not_supported
- method_not_allowed
- state_conflict
- idempotency_conflict
- event_cursor_expired
Expand Down Expand Up @@ -660,8 +652,13 @@ schemas:
IpVersion:
type: string
enum: [ ipv4, ipv6 ]
EntityTagList:
type: string
description: "`*` or a comma-separated list of entity tags, strong or weak (W/ prefix), as RFC 9110 §8.8.3 and §13.1.1 define. An entity tag contains no space, tab or inner double quote. Empty list elements are ignored, as §5.6.1.2 requires of recipients."
pattern: '^(\*|((W/)?"[!#-~\u0080-\u00ff]*")?([ \t]*,[ \t]*((W/)?"[!#-~\u0080-\u00ff]*")?)*)$'
IpAddress:
oneOf:
description: An IPv4 or IPv6 address. Validators must enforce the ipv4 and ipv6 formats; without format assertion, either branch accepts any string.
anyOf:
- type: string
format: ipv4
- type: string
Expand Down
Loading
Loading