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
Was this helpful?