no-path-verbs.md

prohibit use of verbs in api paths (no-path-verbs)

Evaluate whether your service conforms with Level 2 of the Richardson Maturity Model.

Mature RESTful designs represent

• Resources as HTTP paths and
• Operations available for resources as HTTP methods.

⤴️ Back to Rules README

Table of contents

• Table of contents
• Traditional, non-RESTful operations
• RESTful API verbs represented by HTTP method type
• Rule Details
  • Examples of incorrect code for this rule:
    • Common verb violations
    • Paths that contain their operation's name
  • Examples of correct code for this rule:
• When Not To Use It
• Version
• Further Reading

Traditional, non-RESTful operations

Traditional RPC and SOAP calls expose procedure and method calls for CRUD operations. When RPCs and SOAP rarely take HTTP method types into consideration beyond data exchange (e.g., sending data in HTTP request and response bodies).

HTTP method type (verb)	CRUD	Collection (e.g., /pets)	Item (e.g., /pets/{id})
POST	Create	/pets/createPets	/pets/createPet
GET	Read	/pets/getAllPets	/pets/getPetById
POST	Update/Replace	/pets/updateAllPets	/pets/updateById
POST	Update/Modify	/pets/updateBreed	/pets/updateBreedById
POST	Delete	/pets/deleteAllPets	/pets/deletePetsByBreed

RESTful API verbs represented by HTTP method type

RESTful APIs standardize resource operations, e.g., find, get, create, update, with HTTP method method types.

HTTP method type (verb)	CRUD	Collection (e.g., /pets)	Item (e.g., /pets/{id})
POST	Create	201 Created	404 Not Found 409 Conflict (if resource already exists)
GET	Read	200 OK	200 OK 404 Not Found (if resource doesn't exist or invalid)
PUT	Update/Replace	405 Method Not Allowed (unless replacement of every resource is allowed)	200 OK 204 No Content 404 Not Found
PATCH	Update/Modify	405 Method Not Allowed (unless you allow modification of the entire collection)	200 OK 204 No Content 404 Not Found (if ID not found or invalid)
DELETE	Delete	405 Method Not Allowed (unless you want to delete the whole collection; not often desirable)	404 Not Found 200 OK 404 Not Found (if ID not found or invalid)

Rule Details

This rule evaluates API paths for

1. Common (English) verbs
2. Resources with names identical to its operation

Examples of incorrect code for this rule:

Common verb violations

{
  "paths": {
    "/pets/findByStatus": ...,
    "/pets/findByTags": ...,
    "/users/createWithArray": ...,
    "/users/createWithList": ...
  }
}

Paths that contain their operation's name

{
  "paths": {
    "/pets/{petId}/uploadImage": ...,
    "/users/login": ...,
    "/users/logout": ...
  }
}

Examples of correct code for this rule:

{
  "paths": {
    "/pets": ...,  // with <query> input params
    "/pets": ...,  // with <query> input params
    "/pets/{petId}/images": ..., // with uploadImage method
    "/users": ..., // with overloaded operation
    "/users": ..., // with overloaded operation
    "/users/{id}/sessions": ..., // POST
    "/users/{id}/sessions": ...  // DELETE
  }
}

When Not To Use It

Disable this rule only in cases of backwards compatibility.

Richardson Maturity Model (RMM) Level 2

Disabling this rule will affect your RESTful service's maturity level, and your service will not, by definition, achieve Level 2, "HTTP Verbs".

Version

The no-path-verbs rule was introduced to eslint-plugin-swagger in version 0.2.0.

Further Reading

• Documentation source
• Rule source
• Richardson Maturity Model: steps toward the glory of REST

---

⤴️ Back to Rules README