Last updated

path-segment-plural

Enforces plural path segments.

OASCompatibility
2.0✅
3.0✅
3.1✅

API design principles

RESTful API design often uses resources in path segments and those resources are typically plural.

For example, "customers" instead of "customer" because:

  • GET /customers means getting a collection of customers
  • GET /customers/abc means getting customer ABC from the customers collection

As your API grows, you may hit some false positives and may also need to ignore a few outliers. That is, unless you're a purist. Nothing wrong with that.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default off (in recommended configuration).
ignoreLastPathSegmentbooleanIgnores the last path segment if true. Default value: false.
exceptions[string]List of strings to exclude when checking path segments, for example, v1.

An example configuration:

rules:
  path-segment-plural: error

Another example configuration:

rules:
  path-segment-plural:
    severity: error
    ignoreLastPathSegment: true
    exceptions:
      - v1
      - v2
      - people

Examples

Given this configuration:

rules:
  path-segment-plural: error

Example of an incorrect path segment:

paths:
  /customer/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true

Example of a correct path segment:

paths:
  /customers/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true
          description: The customer's ID.

Resources

 
Next page