@apisyouwonthate/style-guide - npm Package Compare versions

Comparing version 1.0.1 to 1.1.0

package.json

 {
   "name": "@apisyouwonthate/style-guide",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Make your HTTP APIs better, faster, stronger, whether they are still being designed (API Design-First) or your organization has flopped various mismatched APIs into production and now you're thinking some consistency would be nice. Using Spectral and OpenAPI\"\"",
@@ -5,0 +5,0 @@ "main": "styleguide.js",

README.md

@@ -40,7 +40,7 @@ # APIs You Won't Hate: API Style Guide
 
-Now you have some things to work on for your API. Thankfully this lot only looks like warnings, so they can be got to those in time (it's not going to [fail continuous integration](https://meta.stoplight.io/docs/spectral/ZG9jOjExNTMyOTAx-continuous-integration) unless [you want it to](https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTg1-spectral-cli#error-results)).
+Now you have some things to work on for your API. Thankfully this lot only looks like warnings, so they can be got to those in time. Warnings are not going to [fail continuous integration](https://meta.stoplight.io/docs/spectral/ZG9jOjExNTMyOTAx-continuous-integration) (unless [you want them to](https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTg1-spectral-cli#error-results)).
 
 ## Backstory
 
-You could write your API Style Guide as a giant manifesto and hope people see it, or you could [automate your API style guide](https://www.apisyouwonthate.com/blog/automated-style-guides-for-rest-graphql-and-grpc)) using a tool like Spectral so that your API Style Guide is enforced at the pull request level. This is one of many parts of a successful API Governance program.
+You could write your API Style Guide as a giant manifesto and hope people see it, or you could [automate your API style guide](https://www.apisyouwonthate.com/blog/automated-style-guides-for-rest-graphql-and-grpc) using a tool like Spectral so that your API Style Guide is enforced at the pull request level. This is an integral part of any successful API Governance program, otherwise you're all just wasting time covering the basics far too late in the game.
 
@@ -50,19 +50,10 @@ Spectral runs on top of OpenAPI and AsyncAPI, powering linting in editors, as a CLI tool, in continuous integration, etc., and comes with its [own set of baked
 
-This NPM package brings together all sorts of advice found in the books and blog posts from [APIs You Won't Hate](https://apisyouwonthate.com) books. If you apply this to APIs in production, this is basically [Phil Sturgeon](https://philsturgeon.com/) judging your API for free. But if you can get this API Style Guide involved in the API Design-First workflow, you're getting free advice on how to design a better API before you waste any time coding, which then means fewer BC breaks as you fix things.
+This NPM package brings together all sorts of advice found in the books and blog posts from [APIs You Won't Hate](https://apisyouwonthate.com) books. If you apply this to APIs in production, this is basically [Phil Sturgeon](https://philsturgeon.com/) judging your API for free. But if you can get this API Style Guide involved in the API Design-First workflow, you're getting free advice on how to design a better API before you waste any time coding, which then means fewer backwards-compatibility breaks as you fix things.
 
 There are [a bunch of other rulesets](https://github.com/stoplightio/spectral-rulesets) you can check out if you feel like making your own API Style Guides, or feel like contributing some new rules here via a pull request.
 
-These two are pretty good:
-
-- [Adidas](https://github.com/adidas/api-guidelines/blob/master/.spectral.yml)
-- [Digital Ocean](https://github.com/digitalocean/openapi/blob/main/spectral/ruleset.yml)
-
 ## 🎉 Thanks
 
-- [Mike Ralphson](https://github.com/MikeRalphson) for kicking off the Spectral CLI and his work on Speccy
-- [Jamund Ferguson](https://github.com/xjamundx) for JUnit formatter
-- [Sindre Sorhus](https://github.com/sindresorhus) for Stylish formatter
-- [Ava Thorn](https://github.com/amthorn) for the Pretty formatter
-- Julian Laval for HTML formatter
-- [@nulltoken](https://github.com/nulltoken) for a whole bunch of amazing features
+- [Andrzej](https://github.com/jerzyn) - Great rules contributed to the Adidas style guide.
+- [Nauman Ali](https://github.com/naumanali-stoplight) - Creating the `no-global-versioning` rule as part of his excellent [style guide blog post series](https://blog.stoplight.io/consistent-api-urls-with-openapi-and-style-guides).
 
@@ -69,0 +60,0 @@ ## 📜 License

styleguide.js

@@ -13,6 +13,7 @@ // These rules dictate actual content of the API: headers, URL conventions, and general
   rules: {
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'api-home': {
       description: 'APIs MUST have a root path (`/`) defined.',
       message: 'Stop forcing all API consumers to visit documentation for basic interactions when the API could do that itself.',
-      severity: "warn",
       given: "$.paths",
@@ -22,8 +23,10 @@ then: {
         function: truthy,
-      }
+      },
+      severity: 'warn',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'api-home-get': {
       description: 'APIs root path (`/`) MUST have a GET operation.',
       message: "Otherwise people won't know how to get it.",
-      severity: "warn",
       given: "$.paths[/]",
@@ -33,4 +36,7 @@ then: {
         function: truthy,
-      }
+      },
+      severity: 'warn',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'api-health': {
@@ -46,7 +52,9 @@ description: 'APIs MUST have a health path (`/health`) defined.',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'api-health-format': {
-      description: 'Health path (`/heath`) SHOULD support Health Check Response Format\"',
+      description: 'Health path (`/heath`) SHOULD support Health Check Response Format',
       message: 'Use existing standards (and draft standards) wherever possible, like the draft standard for health checks: https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check',
       formats: [oas3],
-      severity: "warn",
+      severity: 'warn',
       given: "$.paths.[/health].responses[*].content.*~",
@@ -62,6 +70,8 @@ then: {
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'paths-kebab-case': {
       description: 'Should paths be kebab-case.',
       message: '{{property}} should be kebab-case (lower case and separated with hyphens)',
-      severity: "warn",
+      severity: 'warn',
       given: "$.paths[*]~",
@@ -75,5 +85,6 @@ then: {
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'no-numeric-ids': {
       description: 'Please avoid exposing IDs as an integer, UUIDs are preferred.',
-      severity: 'error',
       given: '$.paths..parameters[*].[?(@property === "name" && (@ === "id" || @.match(/(_id|Id)$/)))]^.schema',
@@ -99,8 +110,10 @@ then: {
         }
-      }
+      },
+      severity: 'error',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'no-http-basic': {
       description: 'Consider a more secure alternative to HTTP Basic.',
       message: 'HTTP Basic is a pretty insecure way to pass credentials around, please consider an alternative.',
-      severity: 'error',
       given: "$.components.securitySchemes[*]",
@@ -113,4 +126,7 @@ then: {
         }
-      }
+      },
+      severity: 'error',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'no-x-headers': {
@@ -125,4 +141,7 @@ description: 'Please do not use headers with X-',
         }
-      }
+      },
+      severity: 'error',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'no-x-response-headers': {
@@ -137,18 +156,36 @@ description: 'Please do not use headers with X-',
         }
-      }
+      },
+      severity: 'error',
+      formats: [oas3],
     },
+    // Author: Andrzej (https://github.com/jerzyn)
+    'request-GET-no-body-oas2': {
+      description: 'A `GET` request MUST NOT accept a `body` parameter',
+      given: '$.paths..get.parameters..in',
+      then: {
+        function: pattern,
+        functionOptions: {
+          notMatch: "/^body$/"
+        }
+      },
+      severity: 'error',
+      formats: [oas2],
+    },
+
+    // Author: Andrzej (https://github.com/jerzyn)
     'request-GET-no-body-oas3': {
       description: 'A `GET` request MUST NOT accept a request body',
-      severity: 'error',
-      formats: [oas3],
       given: "$.paths..get.requestBody",
       then: {
         function: undefinedFunc,
-      }
+      },
+      formats: [oas3],
+      severity: 'error',
     },
-    'headers-lowercase-case': {
+
+    // Author: Andrzej (https://github.com/jerzyn)
+    'headers-hyphenated-pascal-case': {
       description: 'All HTTP headers MUST use Hyphenated-Pascal-Case casing',
-      severity: 'error',
       given: "$..parameters[?(@.in == 'header')].name",
-      message: 'HTTP headers have the first letter of each word capitalized, and each word should be seperated by a hyphen.',
+      message: 'HTTP headers have the first letter of each word capitalized, and each word should be separated by a hyphen.',
       type: "style",
@@ -160,8 +197,9 @@ then: {
         }
-      }
+      },
+      severity: 'error',
     },
+
+    // Author: Andrzej (https://github.com/jerzyn)
     'hosts-https-only-oas2': {
       description: 'ALL requests MUST go through `https` protocol only',
-      severity: 'error',
-      formats: [oas2],
       type: "style",
@@ -182,8 +220,10 @@ message: 'Schemes MUST be https and no other value is allowed.',
         }
-      }
+      },
+      severity: 'error',
+      formats: [oas2],
     },
+
+    // Author: Andrzej (https://github.com/jerzyn)
     'hosts-https-only-oas3': {
       description: 'ALL requests MUST go through https:// protocol only',
-      formats: [oas3],
-      severity: 'error',
       message: 'Servers MUST be https and no other protocol is allowed.',
@@ -196,8 +236,10 @@ given: "$.servers..url",
         }
-      }
+      },
+      formats: [oas3],
+      severity: 'error',
     },
+
+    // Author: Andrzej (https://github.com/jerzyn)
     'request-support-json-oas3': {
       description: 'Every request SHOULD support `application/json` media type',
-      formats: [oas3],
-      severity: "warn",
       message: '{{description}}: {{error}}',
@@ -207,8 +249,10 @@ given: "$.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^",
         function: falsy,
-      }
+      },
+      formats: [oas3],
+      severity: 'warn',
     },
+
+    // Author: Phil Sturgeon (https://github.com/philsturgeon)
     'no-unknown-error-format': {
       description: 'Every error response SHOULD support either RFC 7807 (https://tools.ietf.org/html/rfc6648) or the JSON:API Error format.',
-      formats: [oas3],
-      severity: "warn",
       given: "$.paths.[*]..responses[?(@property.match(/^(4|5)/))].content.*~",
@@ -224,4 +268,8 @@ then: {
         }
-      }
+      },
+      formats: [oas3],
+      severity: 'warn',
     },
+
+    // Author: Nauman Ali (https://github.com/naumanali-stoplight)
     'no-global-versioning': {
@@ -238,5 +286,5 @@ description: 'Using global versions just forces all your clients to do a lot more work for each upgrade. Please consider using API Evolution instead.',
       formats: [oas3],
-      severity: "warn",
+      severity: 'warn',
     }
   }
 };

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

15353

increased by3.13%

Lines of code

255

increased by14.35%

Worsened metrics

Number of lines in readme file

65

decreased by-12.16%

No dependency changes