909fb471ca
* feat: Add Vale configuration and rules * docs: Fix top-level files to match Vale rules * docs: Vale updates for the commands docs * docs: apply Vale updates to the decorator docs * docs: Update guides to match Vale rules * docs: update rules and other content to meet Vale standards * docs: add Vale link and information to CONTRIBUTING * feat: Add GitHub action for Vale * docs: minor editing to readme.md * docs: minor editing to the changelog.md file * docs: minor edits to the join.md file in commands folder * docs: minor edits to lint.md file in the commands directory * docs: minor edit to the login.md file in the commands directory * docs: minor edits to the preview.md file in the commands directory * docs: minor edits to push.md file in the comands directory * docs: minor edits to the info-description-override.md file in the decorators directory * docs: minor edits to the configure-rules.md file in the guides directory * docs: minor edits to custom-plugin.md file in the resources directory * docs: minor editing to the no-http-verbs-in-paths.md file in the rules directory --------- Co-authored-by: Heather Cloward <heathercloward@gmail.com>
2.7 KiB
no-http-verbs-in-paths
Disallows HTTP verbs used in paths.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
flowchart TD
Root ==> Paths
style Paths fill:#codaf9,stroke:#0044d4,stroke-width:5px
List of HTTP verbs:
getheadpostputpatchdeleteoptionstrace
API design principles
API designers generally fall into either a REST or RPC type. The REST type prefers to name paths after resources like "customers", and "payments". And the REST type relies on HTTP methods, like GET, to indicate the action on that resource. It would be considered a design fail to make the path "getcustomers" or "get-customers" or any variation on that. If you're aiming to design RESTful resources, then consider this rule your friend.
To reduce false positives, use the splitIntoWords option.
Imagine a world-famous rock band, the Redockers, and they have an API powering their music tour with one resource "posters".
With the splitIntoWords option enabled, "posters" is identified as a resource and does not trigger a false positive, even though it contains the word post.
Configuration
| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off (in recommended configuration). |
| splitIntoWords | boolean | Matches http verbs when the string is split into words based on casing. This can reduce false positives. Default false. |
An example configuration:
rules:
no-http-verbs-in-paths: error
An example configuration with splitIntoWords enabled:
rules:
no-http-verbs-in-paths:
severity: error
splitIntoWords: true
Examples
Given this configuration:
rules:
no-http-verbs-in-paths: error
Example of an incorrect path:
paths:
/getcustomers:
$ref: ./paths/customer.yaml
Example of a correct path:
paths:
/customers:
$ref: ./paths/customer.yaml
Given the following configuration:
rules:
no-http-verbs-in-paths:
severity: error
splitIntoWords: true
Example of an incorrect path:
paths:
/getCustomers:
$ref: ./paths/customer.yaml
Example of a correct path:
paths:
/getcustomers:
$ref: ./paths/customer.yaml
This last example wouldn't trigger an error because the casing doesn't split "get" into its own word.