#
# Category by uploaders API
#

swagger: '2.0'
info:
  title: Category by uploaders API
  description: Determine who upload to a category, and what
  version: "1.0.0"

#  
# Service endpoint
#

host: tools.wmflabs.org
schemes:
  - http
  - https
basePath: /category-by-uploaders/v1
produces:
  - application/json

#
# Service methods
#

paths:
  /who:
    get:
      summary: Uploaders list
      description: |
        The Who endpoint returns a list of unique contributors who
        uploaded at least one file sorted to this category.
      parameters:
        - name: project
          in: query
          description: "The project database to query (by default commonswiki)"
          default: "commonswiki"
          type: string
        - name: category
          in: query
          description: "The category to seek, without Category: prefix"
          required: true
          type: string
      tags:
        - Uploaders
      responses:
        200:
          description: An array of contributors who uploaded at least a file
          schema:
            type: array
            items:
              type: string
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /contributorsAndFiles:
    get:
      summary: Who upload what information
      description: |
        The contributorsAndFiles endpoint returns a map of the files
        in the specified category grouped by contributors.
      parameters:
        - name: project
          in: query
          description: "The project database to query (by default commonswiki)"
          default: "commonswiki"
          type: string
        - name: category
          in: query
          description: "The category to seek, without Category: prefix"
          required: true
          type: string
      tags:
        - Uploaders
        - Files
      responses:
        200:
          description: A map of the files grouped by contributors
          schema:
            type: array
            items:
              $ref: '#/definitions/FilesByUploader'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /status:
    get:
      summary: API status
      description: Allow to monitor the API and check if it's up.
      tags:
        - Utility
      responses:
        200:
          description: an ALIVE reply
          schema:
            type: string

#
# Service definitions
#

definitions:
  Contributor:
    type: object
    properties:
      name:
        type: string
        description: The contributor username
      uid:
        type: integer
        format: int32
        description: The contributor user id on this project

  File:
    type: object
    properties:
      name:
        type: string
        description: The file name
      url:
        type: string
        description: The URL to the file

  FilesByUploader:
    type: object
    properties:
      uploader:
        $ref: '#/definitions/Contributor'
      count:
        type: integer
        format: Int32
        description: "The number of files uploaded (and in files array)"
      files:
        type: array
        items:
          $ref: '#/definitions/File'
        description: The list of files uploaded

  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
