mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-10 04:21:20 +00:00
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>
129 lines
2.7 KiB
Markdown
129 lines
2.7 KiB
Markdown
# no-http-verbs-in-paths
|
|
|
|
Disallows HTTP verbs used in paths.
|
|
|
|
|OAS|Compatibility|
|
|
|---|---|
|
|
|2.0|✅|
|
|
|3.0|✅|
|
|
|3.1|✅|
|
|
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
|
|
Root ==> Paths
|
|
style Paths fill:#codaf9,stroke:#0044d4,stroke-width:5px
|
|
```
|
|
|
|
List of HTTP verbs:
|
|
- `get`
|
|
- `head`
|
|
- `post`
|
|
- `put`
|
|
- `patch`
|
|
- `delete`
|
|
- `options`
|
|
- `trace`
|
|
|
|
|
|
## 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:
|
|
|
|
```yaml
|
|
rules:
|
|
no-http-verbs-in-paths: error
|
|
```
|
|
|
|
An example configuration with `splitIntoWords` enabled:
|
|
|
|
```yaml
|
|
rules:
|
|
no-http-verbs-in-paths:
|
|
severity: error
|
|
splitIntoWords: true
|
|
```
|
|
|
|
## Examples
|
|
|
|
Given this configuration:
|
|
|
|
```yaml
|
|
rules:
|
|
no-http-verbs-in-paths: error
|
|
```
|
|
|
|
Example of an **incorrect** path:
|
|
|
|
```yaml Bad example
|
|
paths:
|
|
/getcustomers:
|
|
$ref: ./paths/customer.yaml
|
|
```
|
|
|
|
|
|
Example of a **correct** path:
|
|
|
|
```yaml Good example
|
|
paths:
|
|
/customers:
|
|
$ref: ./paths/customer.yaml
|
|
```
|
|
|
|
|
|
Given the following configuration:
|
|
|
|
```yaml
|
|
rules:
|
|
no-http-verbs-in-paths:
|
|
severity: error
|
|
splitIntoWords: true
|
|
```
|
|
|
|
Example of an **incorrect** path:
|
|
|
|
```yaml Bad example
|
|
paths:
|
|
/getCustomers:
|
|
$ref: ./paths/customer.yaml
|
|
```
|
|
|
|
Example of a **correct** path:
|
|
|
|
```yaml Correct example
|
|
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.
|
|
|
|
## Related rules
|
|
|
|
- [configurable rules](./configurable-rules.md)
|
|
- [path-excludes-patterns](./path-excludes-patterns.md)
|
|
|
|
## Resources
|
|
|
|
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-http-verbs-in-paths.ts)
|
|
- [Paths docs](https://redocly.com/docs/openapi-visual-reference/paths/)
|
|
|