swagger: "2.0"
info:
  description: "Atomist Explorer"
  version: 1.0.0
  title: Atomist Explorer
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "info@atomist.com"
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
basePath: /api/v1
tags:
  - name: atomist
    description: Explore your projects
    externalDocs:
      description: Find out more about how Atomist can help visualize and improve your projects
      url: "https://www.atomist.com"
schemes:
  - http
paths:
  /{workspace}/aspects:
    get:
          tags:
            - aspects
          summary: Find all aspects in workspace
          description: Find aspects in workspace
          operationId: findAspects
          produces:
            - application/json
          parameters:
            - name: workspace
              in: path
              description: Workspace id. * for all.
              required: true
              type: string
          responses:
            "200":
              description: successful operation
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/definitions/Category"
            "400":
              description: Invalid workspace id
  /{workspace}/tags:
      get:
            tags:
              - tags
            summary: Find all tags in workspace, including their usage
            description: Find tags in workspace
            operationId: findTags
            produces:
              - application/json
            parameters:
              - name: workspace
                in: path
                description: Workspace id. * for all.
                required: true
                type: string
            responses:
              "200":
                description: successful operation
                schema:
                  type: object
                  properties:
                    list:
                      type: array
                      items:
                        $ref: "#/definitions/Category"
              "400":
                description: Invalid workspace id
  /{workspace}/fingerprints:
    get:
          tags:
            - fingerprints
          summary: Find all fingerprints in workspace
          description: Find fingerprints in workspace
          operationId: findAllFingerprints
          produces:
            - application/json
          parameters:
            - name: workspace
              in: path
              description: Workspace id. * for all.
              required: true
              type: string
          responses:
            "200":
              description: successful operation
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/definitions/Fingerprint"
            "400":
              description: Invalid workspace id
  /{workspace}/fingerprint/{type}:
    get:
          tags:
            - fingerprints
          summary: Find all fingerprints of a given type in the workspace
          description: Find fingerprints of a given type in workspace
          operationId: findFingerprintsByType
          produces:
            - application/json
          parameters:
            - name: workspace
              in: path
              description: Workspace id. * for all.
              required: true
              type: string
            - name: type
              in: path
              description: Fingerprint type
              required: true
              type: string
          responses:
            "200":
              description: successful operation
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/definitions/Fingerprint"
            "400":
              description: Invalid status value 
  /{workspace}/fingerprint/{type}/{name}:
    get:
          tags:
            - fingerprints
          summary: Show the distribution of a fingerprint in the workspace
          description: Show the distribution of a fingerprint in the workspace, in a tree structure where the outer ring is repository
          operationId: findFingerprintsByNameAndType
          produces:
            - application/json
          parameters:
            - name: workspace
              in: path
              description: Workspace id. * for all.
              required: true
              type: string
            - name: type
              in: path
              description: Fingerprint type
              required: true
              type: string
            - name: name
              in: path
              description: Fingerprint name. Use "*" to show all fingerprints of type
              required: true
              type: string
            - name: byOrg
              in: query
              description: Introduce a tree layer by organization
              type: string
              enum:
                - true
                - false
              required: false
              default: true
            - name: progress
              in: query
              description: Show progress to ideal
              type: string
              enum:
                - true
                - false
              required: false
              default: false
            - name: otherLabel
              in: query
              description: If set, returns a response for all repos, whether or not the technology is present, with the label being shown
              type: string
              required: false
            - name: trim
              in: query
              description: Trim outer ring (repositories). Only relevant if name=*
              type: string
              enum:
                - true
                - false
              required: false
              default: false
          responses:
            "200":
              description: successful operation
              schema:
                type: object
                properties:
                  tree:
                    $ref: "#/definitions/Tree"
            "400":
              description: Invalid status value
  /{workspace}/drift:
    get:
        tags:
          - drift
        summary: Show drift in the workspace
        description: Show drift in the workspace, in a tree structure where the outer ring is fingerprint
        operationId: drift
        produces:
          - application/json
        parameters:
          - name: workspace
            in: path
            description: Workspace id. * for all.
            required: true
            type: string
        parameters:
          - name: percentile
            in: query
            description: Entropy percentile (e.g. 80). Only show aspects with entropy above this.
            required: false
            type: integer
            format: int32
            default: 0
          - name: band
            in: query
            description: Introduce a ring for size band
            type: string
            enum:
              - true
              - false
            required: false
            default: false
        parameters:
          - name: type
            in: query
            description: Aspect name (fingerprint type) to show drift for
            required: false
            type: string
        responses:
          "200":
            description: successful operation
            schema:
              type: object
              properties:
                tree:
                  $ref: "#/definitions/Tree"
          "400":
            description: Invalid status value
  /{workspace}/ideal/{id}:
        put:
            tags:
              - ideal
            summary: Set an ideal fingerprint
            description: Set an ideal fingerprint
            operationId: setIdeal
            produces:
              - application/json
            parameters:
              - name: workspace
                in: path
                description: Workspace id
                required: true
                type: string
              - name: id
                in: path
                description: Ideal id
                required: true
                type: string
            responses:
              "201":
                description: successful operation
              "400":
                description: Invalid status value
  /{workspace}/entropy/{type}/{name}:
        put:
            tags:
              - entropy
            summary: Calculate entropy for the given fingerprint
            description: Calculate entropy for the given fingerprint
            operationId: calculateEntropy
            produces:
              - application/json
            parameters:
              - name: workspace
                in: path
                description: Workspace id
                required: true
                type: string
              - name: type
                in: path
                description: Fingerprint type
                required: true
                type: string
              - name: name
                in: path
                description: Fingerprint name
                required: true
                type: string
            responses:
              "201":
                description: successful operation
              "400":
                description: Invalid status value
  /{workspace}/explore:
    get:
          tags:
            - repositories
          summary: Find all repositories in workspace matching one or more tags
          description: Find all repositories in workspace matching one or more tags
          operationId: findByTag
          produces:
            - application/json
          parameters:
            - name: workspace
              in: path
              description: Workspace id. * for all.
              required: true
              type: string
            - name: tags
              in: query
              description: Comma-separate list of tags to search for.
              required: false
              type: string
            - name: byOrg
              in: query
              description: Introduce a tree layer by organization
              type: string
              enum:
                - true
                - false
              required: false
              default: true
          responses:
            "200":
              description: successful operation
              schema:
                  type: object
                  properties:
                    tags:
                      type: array
                      description: Thing
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: Tag name
                          count:
                            description: Occurrence among matching repositories
                            type: integer
                            format: int32
                    selectedTags:
                      type: array
                      description: Selected tags
                      items:
                        type: string
                    tree:
                      description: Org/repositories/tags
                      $ref: "#/definitions/Tree"
            "400":
              description: Invalid workspace id

components:
  schemas:
    Aspect:
      type: object
      properties:
        name:
          type: string
          description: Human readable aspect name
        type:
          type: string
          description: Aspect name
        description:
          type: string
          description: Description
        url:
          type: string
          description: URL for futher information

definitions:
  Category:
    properties:
      category:
        type: string
        description: Category tag
      count:
        type: integer
        format: int32
      aspects:
        type: array
        items:
          $ref: "#/components/schemas/Aspect"
        description: Aspects in this category
  Fingerprint:
    properties:
      type:
        type: string
        description: Fingerprint type
      name:
        type: string
        description: Fingerprint name
      variants:
        type: integer
        format: int32
      count:
        type: integer
        format: int32
      entropy:
        type: integer
        format: float
        description: Entropy across the organization for this fingerprint.
  Tree:
    properties:
      name:
        type: string
        description: Name of this level
      children:
        type: array
        items:
          # Probably need to do https://stackoverflow.com/questions/36866035/how-to-refer-to-enclosing-type-definition-recursively-in-openapi-swagger
          $ref: "#/definitions/Tree"
    required:
      - name