APIs You Won't Hate - The Ruleset

[philsturgeon]

I've been working on an API's You Wont Hate themed custom Spectral ruleset that'll give you some rather opinionated feedback on how to build a better API, mostly taking rules from the book, or from general best practice figured out since then, all by looking at your OpenAPI descriptions.

It's got some fairly fun rules in there which you might want to add to your ruleset as you start automating your API Style Guide:

No HTTP Basic

  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: warn
    given: $.components.securitySchemes[*]
    then:
      field: scheme
      function: pattern
      functionOptions:
        notMatch: basic

Make your errors either follow JSON:API or RFC 7807

  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.*~
    then:
      function: enumeration
      functionOptions:
        values:
        - application/vnd.api+json
        - application/problem+xml
        - application/problem+json

Here are some idea for rules that I'd love folks to take a swing at here:

1. Make sure every post/put/delete/patch endpoint has some sort of security

2. Numeric IDs are awful, use something else like maybe UUID (but don't specify the format they have to use. Just complain about numeric ID"

3. No global versions in server URL, path, or headers. Might need a few rules here.

4. Mime type should have "; charset=utf-8" on the end or how do we know if its UTF-8?

5. No "(e/E)rror" string in 2xx, in either the JSON property names or any of the text is outputs.

Anyone that successfully makes one of these custom rules will have 100 trees donated to our community forest in their name.

[SensibleWood]

@philsturgeon: Approach to number 1 (apologies involves a custom function but couldn't work out how to deal with an empty object in JSON Path - sure there must be a way - and the built-in functions didn't seem to have anything available).

Given the following OpenAPI document:

openapi: 3.0.3
info:
  title: Scratch
  version: 1.0.0
paths:
  /crap:
    post:
      requestBody:
        description: Scratch
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created
  /stupid:
    post:
      requestBody:
        description: Scratch
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created
      security:
        - {}
  /better:
    post:
      requestBody:
        description: Scratch
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created
      security:
        - babaGhanoush: []
components:
  securitySchemes:
    babaGhanoush:
      type: apiKey
      name: babaGhanoush
      in: header

The following ruleset:

extends: spectral:oas
functions: [empty-object]
rules:
  operation-operationId: off
  oas3-api-servers: off
  info-contact: off
  operation-description: off
  operation-tags: off
  openapi-tags: off
  info-description: off
  security-must-be-enforced-for-unsafe-endpoints:
    message: Get some security you f**king cretin
    severity: error
    given: "$.paths.*[?(@property == 'post' || @property == 'put' || @property == 'patch' || @property == 'delete')]"
    then:
      - field: security
        function: truthy
  security-object-must-not-be-a-hacked-in-empty-object:
    message: "{{error}}"
    severity: error
    given: "$.paths.*[?(@property == 'post' || @property == 'put' || @property == 'patch' || @property == 'delete')].security.*"
    then:
      function: empty-object

And this custom function:

module.exports = (security) => {
    if (Object.keys(security).length === 0) {
      return [{message: 'Security Requirement objects with no properties define no security'}]
    }
}

You get the following:

➜  spectral-evidence spectral lint --ruleset apis-you-wont-hate-ruleset.yaml apis-you-wont-hate-openapi.yaml
OpenAPI 3.x detected

/Users/chris/Documents/git/github/spectral-evidence/apis-you-wont-hate-openapi.yaml
  7:10  error  security-must-be-enforced-for-unsafe-endpoints        Get some security you f**king cretin                                paths./crap.post
 29:11  error  security-object-must-not-be-a-hacked-in-empty-object  Security Requirement objects with no properties define no security  paths./stupid.post.security[0]

✖ 2 problems (2 errors, 0 warnings, 0 infos, 0 hints)

➜  spectral-evidence

Tree-worthy answer?

[SensibleWood]

@philsturgeon - any trees on the horizon for this answer?

[savage-alex]

@SensibleWood I often see APIs with security defined at the API level (outside of the paths definition) could we handle that ?

[philsturgeon]

@SensibleWood ill definitely take a look at this mate I’m just rammed at the moment!