paths-max-depth
Since 0.0.1 · In the rulesets: Recommended at warning, Strict at warning, All at error
This rule checks that no path has more than 4 segments, or the number configured. A segment is
the text between two slashes; /users/{userId}/posts has three.
Rule details
A path of six segments spells out a chain of ownership that the client must walk on every
request, /users/{userId}/posts/{postId}/comments/{commentId}, when the last identifier alone
names the resource. Shorter paths are easier to read, to route and to keep when the ownership
changes.
The rule reports Path URL is too much nested (...) on each path over the limit.
Configuration
A positive integer: the number of segments allowed. 4 by default.
Configuration example. Up to 6 segments.
commands:
lint:
rules:
paths-max-depth:
- warning
- 6
Examples
Good. Two segments.
paths:
/users/{userId}:
get:
summary: Get a user by ID
Bad. Six segments with the default limit.
paths:
/users/{userId}/posts/{postId}/comments/{commentId}:
get:
summary: Get a comment of a post of a user
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
paths-max-depth: off