Merge branch 'ruleset' of https://github.com/adidas/api-guidelines into ruleset

hal.yaml

@@ -0,0 +1,68 @@
+# $id: http://supermodel.io/andrzej/hAL
+# $schema: http://json-schema.org/draft-04/schema#
+
+title: HAL
+description: JSON Hypertext Application Language. Definition of [HAL message format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
+type: object
+# required:
+#   - errorCauser
+properties:
+  # errorCauser:
+  #   type: string
+  _links:
+    type: object
+    additionalProperties:
+      anyOf:
+      - $ref: '#/definitions/halLinkObject'
+      - type: array
+        items:
+          - $ref: '#/definitions/halLinkObject'
+    properties:
+      curies:
+        anyOf:
+          - $ref: '#/definitions/halCuriesLink'
+          - type: array
+            items:
+              - $ref: '#/definitions/halCuriesLink'
+  _embedded:
+    type: object
+    additionalProperties:
+      anyOf:
+        - $ref: '#'
+        - type: array
+          items:
+            - $ref: '#'
+definitions:
+  halLinkObject:
+    title: HAL Link Object
+    type: object
+    properties:
+      href:
+        type: string
+      templated:
+        type: boolean
+      type:
+       type: string
+      deprecation:
+        type: string
+      name:
+        type: string
+      profile:
+        type: string
+      title:
+        type: string
+      hreflang:
+        type: string
+    required:
+      - href
+  halCuriesLink:
+    title: HAL Curies Link
+    allOf:
+      - type: object
+        properties:
+          templated:
+            enum:
+              - true
+        required:
+          - templated
+      - $ref: '#/definitions/halLinkObject'

problem.yaml

@@ -0,0 +1,19 @@
+# $id: http://supermodel.io/adidas/api/ProblemDetail
+# $schema: http://json-schema.org/draft-07/schema#
+title: Problem Details for HTTP APIs
+description: Definition of [RFC7807](https://tools.ietf.org/html/rfc7807) problem detail
+type: object
+properties:
+  type:
+    type: string
+  title:
+    type: string
+  status:
+    type: number
+  detail:
+    type: string
+  instance:
+    type: string
+required:
+  - title
+  - detail

ruleset.md

@@ -20,4 +20,4 @@
 - a successful and finished async api request returns `303` response code and sends the target resource location in the `Link` header
 - `URI` template ([RFC 6570](https://tools.ietf.org/html/rfc6570)) cannot contain a `-` character
 - `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation
-- `HTTP` headers SHOULD NOT include `X-` headers (https://tools.ietf.org/html/rfc6648). All non-standard headers are named without the `X-` prefix.
+- `HTTP` headers SHOULD NOT include [`X-` headers](2). All non-standard headers are named without the `X-` prefix.

spectral.yml

@@ -0,0 +1,141 @@
+extends: spectral:oas2
+rules:
+  operation-operationId: false
+  operation-tags: info
+  operation-2xx-response: error
+  paths-camelCase:
+    description: All YAML/JSON paths MUST follow camelCase
+    severity: warn
+    recommended: true
+    message: "{{property}} is not camelCase: {{error}}"
+    given: $.paths[*]~
+    then:
+      function: pattern
+      functionOptions:
+        # match: "/^(\/{1}(([{]?[a-z])[A-Za-z0-9]*[}]?)*)+$/" # - more generic one, allows /asasd{asdas}sadas pattern but also not closed braces
+        match: "^\/([a-z][a-zA-Z0-9]+)?(\/[a-z][a-zA-Z0-9]+|\/{[a-z][a-zA-Z0-9]+})*$" # doesn't allow /asasd{asdas}sadas pattern or not closed braces
+  definitions-camelCase-alphanumeric:
+    description: All YAML/JSON definitions MUST follow fields-camelCase and be ASCII alphanumeric characters or `_` or `$`.
+    severity: error
+    recommended: true
+    message: "{{property}} MUST follow camelCase and be ASCII alphanumeric characters or `_` or `$`."
+    given: $.definitions[*]~
+    then:
+      function: pattern
+      functionOptions:
+        match: "/^[a-z$_]{1}[A-Z09$_]*/"
+  properties-camelCase-alphanumeric:
+    description: All JSON Schema properties MUST follow fields-camelCase and be ASCII alphanumeric characters or `_` or `$`.
+    severity: error
+    recommended: true
+    message: "{{property}} MUST follow camelCase and be ASCII alphanumeric characters or `_` or `$`."
+    given: $.definitions..properties[*]~
+    then:
+      function: pattern
+      functionOptions:
+        match: "/^[a-z$_]{1}[A-Z09$_]*/"
+  protocol-https-only:
+    description: "ALL requests MUST go through `https` protocol only"
+    recommended: true
+    severity: error
+    type: "style"
+    message: "Schemes MUST be https and no other value is allowed."
+    given: $
+    then:
+      field: schemes
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          items:
+            type: string
+            enum: ["https"]
+          maxItems: 1
+  request-GET-no-body:
+    description: A `GET` request MUST NOT accept a `body` parameter
+    severity: error
+    given: $.paths..get.parameters..in
+    then:
+      function: pattern
+      functionOptions:
+        notMatch: "/^body$/"
+  response-success-hal: # schemes and/or produces
+    description: All success responses MUST be of media type `application/hal+json`
+    severity: error
+    given: $.paths..responses[?( @property >= 200 && @property < 300 )]
+    recommended: true
+    severity: error
+    type: "style"
+    message: "Response documents MUST follow application/hal+json: {{error}}"
+    then:
+      field: schema
+      function: schema
+      functionOptions:
+        schema:
+          $ref: ./hal.yaml
+  response-error-problem: # schemes and/or produces
+    description: All error responses MUST be of media type `application/problem+json`
+    severity: error
+    given: $.paths..responses[?( @property >= 400 && @property < 600 )]
+    recommended: true
+    severity: error
+    type: "style"
+    message: "Error response document MUST follow application/problem+json: {{error}}"
+    then:
+      field: schema
+      function: schema
+      functionOptions:
+        schema:
+          $ref: ./problem.yaml
+  request-support-json: # This will have to take into account the schemes as well as consumes parameter
+    description: Every request SHOULD support `application/json` media type
+    severity: warn
+    message: "{{description}}: {{error}}"
+    recommended: true
+    given: "$..consumes"
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          contains:
+            type: string
+            enum:
+              - application/json
+  uri-template-cannot-dash:
+    description: The `URI` template ([RFC 6570](https://tools.ietf.org/html/rfc6570)) cannot contain a `-` character
+    severity: error
+    recommended: true
+    message: "{{property}}: {{description}}"
+    given: $.paths[*]~
+    then:
+      function: pattern
+      functionOptions:
+        notMatch: "/-/"
+  # Needs update of JSON Schema in spectral to draft-07 or newer to implement if-then statements
+  # headers-hyphenated-pascal-case:
+  #   description: All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation
+  #   severity: error
+  #   given: $..parameters[*].in
+  # heders-no-x-headers:
+  #   description: All `HTTP` headers SHOULD NOT include `X-` headers (https://tools.ietf.org/html/rfc6648). All non-standard headers are named without the `X-` prefix.
+  #   severity: warning
+  #   given: $..parameters[*].in
+
+## Other rules which are redundant or not feasible
+  
+  # fields-date-iso8601:
+  #   description: Date and time MUST follow [`ISO 8601` standard](https://www.iso.org/iso-8601-date-and-time-format.html)
+  #   severity: error
+  # fields-language-iso639:
+  #   description: Language codes MUST follow [`ISO 639` standard](https://www.iso.org/iso-639-language-codes.html)
+  #   severity: error
+  # fields-country-iso3166:
+  #   description: Country codes MUST follow [`ISO 3166 alpha-2` standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+  #   severity: error
+  # fields-currency-iso4217:
+  #   description: Currency codes MUST follow [`ISO 4217` standard](https://en.wikipedia.org/wiki/ISO_4217)
+  #   severity: error
+  # response-303-async-link-header:
+  #   description: A successful and finished async api request returns `303` response code and sends the target resource location in the `Link` header
+  #   severity: hint