zally-api.yaml

openapi: '3.0.1'

info:
  title: Zally - Zalando's API Linter
  description: |
    Zally is a quality assurance tool. It's main purpose is to check the complience of
    API specifications to a specific set of API design rules.

    The service is able to lint the API specification in OpenAPI format. The result of
    the linting is a set of Violations. A violation contains information about the violated
    rule, its severity, and path of the violation in the specification document.

    The API also provides a result and statistics endpoint. It contains aggregated statics like
    the number of linting requests and the number of checked endpoints. Additionally, all
    linting results and the linted API specifications can be retrieved.

  version: "2.2.0"
  x-api-id: 48aa0090-25ef-11e8-b467-0ed5f89f718b
  x-audience: company-internal
  contact:
    name: Team API Management
    email: team-api-management@zalando.de
    url: "http://tech.zalando.de"

externalDocs:
  description: Open Source project's page
  url: https://opensource.zalando.com/zally/

servers:
- url: "https://zally.on.inter.net"
  description: Production Zally Web UI instance

paths:
  '/api-violations':
    post:
      summary:
        API Violations
      description: |
        The API Violations endpoint validates given Swagger Specification
        against the rules defined in *Zalando* RESTful API Guidelines
        (http://zalando.github.io/restful-api-guidelines/).

        A successful response includes the list of violations grouped by
        the API Guidelines rules.

        If an api definition is supplied via url then any non-successful
        responses from that will be passed on. For example you may be
        using Zally without authentication but supply a password
        protected url and still get a `401 Unauthorized` response.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LintingRequest'
      responses:
        200:
          description: API swagger is OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LintingResponse'
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: The URI where the validation result can be rerequested.
        400:
          description: Input file not parsable
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
        default:
          description: Error object
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
      - oauth2:
        - uid

  '/api-violations/{externalId}':
    get:
      summary:
        Get previous generated validation result
      description: |
        Retreive a previous validation result in the same format as when
        it was originally processed.

        If the idenfied validation result cannot be found then a
        `404 Not Found` response is returned.
      parameters:
      - $ref: '#/components/parameters/ExternalId'
      responses:
        200:
          description: API swagger is OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LintingResponse'
        404:
          description: No such API review
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
        default:
          description: Error object
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
      - oauth2:
        - uid

  '/supported-rules':
    get:
      summary:
        Suported Rules
      description: |
        Returns a list of rules which are supported by a current Zally
        installation.
      parameters:
      - $ref: '#/components/parameters/RulesType'
      - $ref: '#/components/parameters/IsActive'
      responses:
        200:
          description: List of supported rules is successfully returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedRulesResponse'
        400:
          description: One of the query parameters is incorrect
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
        default:
          description: Error object
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
      - oauth2:
        - uid

  '/review-statistics':
    get:
      summary:
        Provides query capabilites for linting summaries and automatically computed review statistics.
      description: |
        Returns a list of all linting results and review statistics for a given
        interval in time. If none of the query parameters is supplied, a list of
        all linting results and review statistics for the last week is returned.
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/UserAgent'
      responses:
        200:
          description: List of queried review statistics
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ReviewStatisticsResponse'
        400:
          description: One of the query parameters is incorrect
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
        default:
          description: Error object
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
      - oauth2:
        - uid


components:

  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://identity.zalando.com/oauth2/token
          scopes:
            uid: Default scope to access Zally API

  parameters:
    RulesType:
      name: type
      in: query
      description: Rules Type
      required: false
      schema:
        type: string
        x-extensible-enum:
        - MUST
        - SHOULD
        - COULD
        - MAY
        - HINT
    IsActive:
      name: is_active
      in: query
      description: Is Rule Active
      required: false
      schema:
        type: boolean
    From:
      name: from
      in: query
      description: All review statistics from this day
      required: false
      schema:
        type: string
        format: date
    To:
      name: to
      in: query
      description: All review statistics until this day, only works in conjunction with from parameter
      required: false
      schema:
        type: string
        format: date
    UserAgent:
      name: user_agent
      in: query
      description: Review statistics requested with the specified User-Agent
      required: false
      schema:
        type: string
    ExternalId:
      name: externalId
      in: path
      description: Identifier of a previous validation result
      required: true
      schema:
        type: string
        format: uuid

  schemas:
    LintingRequest:
      type: object
      description: |
        Request containing a swagger definition file. One of the following fields must be provided:
        api_definition, api_definition_string, or api_definition_url.
      properties:
        api_definition:
          type: object
          description: Specification object in OpenAPI format
        api_definition_string:
          type: string
          description: Raw API Specification string in OpenAPI format
        api_definition_url:
          type: string
          description: Link to the specification in OpenAPI format
        ignore_rules:
          type: array
          items:
            type: string
          description: List of rule ids to be ignored

    LintingResponse:
      type: object
      description: Linting Response
      required:
      - violations
      - violations_count
      properties:
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
          description: List of violations
        message:
          type: string
          description: Custom server message
        violations_count:
          $ref: '#/components/schemas/ViolationsCount'
        api_definition:
          type: string
          description: Specification object in OpenAPI format

    SupportedRulesResponse:
      type: object
      description: Supported Rules
      required:
      - supported_rules
      properties:
        supported_rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'

    ReviewStatisticsResponse:
      type: object
      description: Linting results and review statistics for a given interval in time
      required:
      - total_reviews
      - total_reviews_deduplicated
      - successful_reviews
      - number_of_endpoints
      - must_violations
      - should_violations
      - may_violations
      - hint_violations
      properties:
        total_reviews:
          type: integer
          format: int32
          example: 23
          description: Total number of lintings
        total_reviews_deduplicated:
          type: integer
          format: int32
          example: 12
          description: Unique APIs linted
        successful_reviews:
          type: integer
          format: int32
          example: 17
          description: Number of successful lintings
        number_of_endpoints:
          type: integer
          format: int32
          example: 10
          description: Number of endpoints in the linted APIs
        must_violations:
          type: integer
          format: int32
          example: 123
          description: Number of MUST violations
        should_violations:
          type: integer
          format: int32
          example: 81
          description: Number of SHOULD violations
        may_violations:
          type: integer
          format: int32
          example: 32
          description: Number of MAY violations
        hint_violations:
          type: integer
          format: int32
          example: 5
          description: Number of HINTS

    Violation:
      type: object
      description: Violation Object
      required:
      - title
      - description
      - violation_type
      - paths
      properties:
        title:
          type: string
          description: Violation title
        description:
          type: string
          description: Violation text
        violation_type:
          $ref: '#/components/schemas/RuleType'
        rule_link:
          type: string
          description: Violated rule URL
        paths:
          type: array
          items:
            type: string
          description: Violated paths
        pointer:
          type: string
          description: JsonPointer to the violated path in the specification
        start_line:
          type: integer
          format: int32
          example: 1
          description: The line starting the violated location, if known
        end_line:
          type: integer
          format: int32
          example: 5
          description: The line ending the violated location, if known

    ViolationsCount:
      type: object
      description: Violation Count
      required:
      - must
      - should
      - may
      - could
      - hint
      properties:
        must:
          type: integer
          format: int32
        should:
          type: integer
          format: int32
        may:
          type: integer
          format: int32
        could:
          type: integer
          format: int32
        hint:
          type: integer
          format: int32

    Rule:
      type: object
      description: Rule
      required:
      - title
      - code
      - type
      - url
      - is_active
      properties:
        title:
          type: string
          description: Rule title
          example: 'Do Not Use URI Versioning'
        code:
          type: string
          description: Rule id
          example: '115'
        type:
          $ref: '#/components/schemas/RuleType'
        url:
          type: string
          description: Link to the rule's description
          example: 'https://zalando.github.io/restful-api-guidelines/compatibility/Compatibility.html#must-do-not-use-uri-versioning'
        is_active:
          type: boolean
          description: Shows whether the rule is activated
          example: true

    RuleType:
      type: string
      x-extensible-enum:
      - MUST
      - SHOULD
      - COULD
      - MAY
      - HINT
      description: Rule type / severity