require-plural-paths.md

Require plural nouns in API paths (require-plural-paths)

The require-plural-paths rule enforces consistent usage of plural nouns for all resources.

⤴️ Back to Rules README

Table of contents

• Table of contents
• Rule Details
  • Examples of incorrect code for this rule
  • Examples of correct code for this rule
• When Not To Use It
• Version
• Further Reading
  • Sources
  • Resources

Rule Details

Mature RESTful designs represent

• HTTP paths as resources and
• HTTP methods as operations available for those resources.

For example, we might represent a customer and her purchase orders:

// let customer =
{
  "id":"d5e124d9",
  "orders":[
    {
      "id":"1330334826",
      "items":[
        {
          "name":"Women's Lace Trim Half Sleeve Floral Print Top Skirt"
        }
      ]
    }
  ]
}

In object-oriented languages, we commonly use "dot" syntax to access the items she purchased in a single order:

const productsOrdered = customer.orders[0].items;

REST allows us to use a similar syntax for accessing (and modifying) an object's properties with HTTP. Instead of using "dot" syntax, however, we use URI paths (aka, "resources"):

GET /customers/d5e124d9/orders/1330334826/items

Whether we use dots (OOP) or slashes (HTTP), we represent customers using the same words: we use a common interface. An interface simply allows us to reference lots of different data using the same terminology. Therefore, interfaces can be seen as collections of data with a contractural nomenclature. Given this point of view, most RESTful API conventions recommend plural nouns in API paths.

REST API debates

Whether or not a convention recommends singular or plural nouns, almost all guidelines stress consistency and resource uniformity.

Examples of incorrect code for this rule

❌ The require-plural-paths rule throws an error whenever swaggerApi.path definitions use singular nouns instead of plural:

/pet/{uuid}
/store/{id}/inventory
/user/{uuid}/order/{id}

Examples of correct code for this rule

✅ The require-plural-paths rule validates swaggerApi.paths with resources that use the plural case:

/pets/{uuid}
/stores/{id}/inventory
/users/{uuid}/orders/{id}

ℹ️ API path parameters are not pluralized

Parameters -- resources with dynamic values -- are not validated for plural case. For example, the following resource literals are invalid:

/store/order/{orderId}

Per style guidelines, the correct representation is

/stores/orders/{orderId}

📝 Note that in both examples, the grammatical categorization of the {orderId} parameter did not change.

When Not To Use It

Disable this rule if your product's style guidelines

• Require singular nouns instead of plural, or
• Provide unambiguous and testable instructions for singular and plural noun use cases

Version

The require-plural-paths rule was introduced to eslint-plugin-swagger in version 0.1.0.

Further Reading

Sources

• Documentation source
• Rule source

Resources

• REST API Tutorial's section on "Pluralization"
• RESTful API Design. Best Practices in a Nutshell: "Use Consistently Plural Nouns"
• RESTful API Design: plural nouns and concrete names

---

⤴️ Back to Rules README