swagger.yaml

swagger: '2.0'
info:
  title: BirdFeed
  description: Provide for and analyze metrics on the quality of spoken English.
  version: 1.0.0
  contact:
    name: David Stancu, Paulina Levit
    email: dstancu@nyu.edu
  license:
    name: MIT
    url: https://github.com/mach-kernel/birdfeed/blob/master/LICENSE
host: birdfeed.herokuapp.com
schemes:
  - https
securityDefinitions:
  birdcage:
    type: oauth2
    authorizationUrl: https://birdfeed.herokuapp.com/v1/auth
    flow: implicit
    scopes:
      client: Allows a BirdFeed consumer to register participants
      participant: Allows a Participant resource to record scores from a client, retrieve samples and experiments
      user: Allows non-participant users to modify samples and experiments
      administrator: Allows unrestricted access to all resources
basePath: /v1
produces:
  - application/json
paths:
  /sample:
    get:
      summary: Retrieve samples
      description: |
        Retrieve a list of audio sample resources. By default, a limit of 10 samples are returned. These will be the most recent samples created.
      parameters:
        - name: limit
          in: query
          description: Number of audio samples to return
          type: integer
      tags:
        - Samples
      responses:
        200:
          description: An array of samples
          schema:
            type: array
            items:
              $ref: '#/definitions/Sample'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - participant
          - user
          - administrator
  /sample/set:
    post:
      summary: Retrieve a set of audio samples
      description: |
        Retrieve a set of audio sample resources by ID. If a resource cannot be found, that resource will not be returned. Upon passing an empty array or an array with all invalid IDs, an empty set will be returned.
      parameters:
        - name: ids
          in: body
          description: Array of audio sample IDs
          schema:
            type: array
            items:
              type: string
          required: true
      tags: 
        - Samples
      responses: 
        200:
          description: An array of the desired samples. 
          schema:
            type: array
            items:
              $ref: '#/definitions/Sample'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - participant
          - user
          - administrator
  /sample/search:
    get:
      summary: Retrieve audio sample(s) by specified criterion.
      description: | 
        Retrieve one or many audio samples by the specified search criterion. Only one criteria should be specified for a search. All matching resources will be returned, in the case of no matching resources, an empty set will be returned.
      parameters:
        - name: name
          in: query
          description: The name of the audio sample file
          type: string
        - name: tags
          in: query
          description: Tags associated with sample file
          type: array
          items: 
            type: string
        - name: date
          in: query
          description: Date when sample was created. Time will be used if provided.
          type: string
          format: date-time
      tags:
        - Samples
      responses: 
        200: 
          description: An array of the desired samples.
          schema:
            type: array
            items:
              $ref: '#/definitions/Sample'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'    
      security:
        - birdcage:
          - participant
          - user
          - administrator
  /sample/{id}:
    get: 
      summary: Audio samples
      description: |
        Retrieve an audio sample by its ID
      parameters:
        - name: id
          in: path
          description: ID of audio sample resource
          required: true
          type: integer
      tags:
        - Samples
      responses:
        200:
          description: An audio sample resource
          schema:
            $ref: '#/definitions/Sample'
        500:
          description: Unexpected error
          schema: 
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - participant
          - user
          - administrator
    post:
      summary: Audio samples
      description: |
        Modify an audio sample by its ID. If a field is left empty, it will not be modified.
      parameters: 
        - name: id
          in: path
          description: ID of audio sample resource
          type: integer
          required: true
        - name: modify
          in: body
          description: Modified fields 
          schema:
            type: object
            properties:
              name:
                type: string
              expected_score:
                type: integer
              s3_url:
                type: string
              tags:
                type: array
                items:
                  type: string
          required: true
      tags:
        - Samples
      responses:
        200:
          description: Modified Sample resource
          schema: 
            $ref: '#/definitions/Sample'
        500: 
          description: Unexpected error
          schema: 
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - user
          - administrator
    delete:
      summary: Audio samples
      description: |
        Delete an audio sample by its ID
      parameters:
        - name: id
          in: path
          description: ID of audio sample resource
          type: integer
          required: true
      tags: 
        - Samples
      responses:
        200:
          description: Sample was successfully deleted
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error' 
      security:
        - birdcage:
          - user
          - administrator
  /sample/create:
    post:
      summary: Create audio samples
      description: |
        Create an audio sample. Returns ID of newly created resource. 
      parameters: 
        - name: sample
          in: body
          description: The filename, AWS link for the location of the sound file, tags, and expected score (enter -1 for no expected score)
          schema:
            type: object
            properties:
              name: 
                type: string
              s3_url:
                type: string
              expected_score:
                type: integer
              tags:
                type: array
                items:
                  type: string
          required: true
      tags: 
        - Samples
      responses:
        201:
          description: The ID of the newly created Sample resource
          schema:
            type: string
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - user
          - administrator
  /experiment/{id}:
    get:
      summary: Retrieve experiment by ID
      description: |
        Retrieves an experiment resource by its ID
      parameters:
        - name: id
          in: path
          description: ID of experiment resource
          type: string
          required: true
      tags: 
        - Experiments 
      responses:
        200:
          description: An experiment resource
          schema:
            $ref: '#/definitions/Experiment'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - participant
          - user
          - administrator
    post:
      summary: Modify an experiment by ID.
      description: |
        Modify an experiment by its ID. If a field is left empty, it will not be modified.
      parameters:
        - name: id
          in: path
          description: ID of experiment resource
          type: string
          required: true
        - name: modify
          in: body
          description: Modified fields
          schema:
            type: object
            properties:
              name:
                type: string
              expiry_date:
                type: string
                format: date-time
              tags: 
                type: array
                items:
                  type: string
          required: true
      tags:
        - Experiments
      responses:
        200:
          description: Modified experiment resource
          schema:
            $ref: '#/definitions/Experiment'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - user
          - administrator
    delete:
      summary: Delete an experiment by ID
      description: | 
        Delete an experiment by its ID
      parameters:
        - name: id
          in: path
          description: ID of experiment resource
          type: string
          required: true
      tags:
        - Experiments
      responses: 
        200:
          description: Experiment was successfully deleted
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - user
          - administrator

  /experiment/create:
    post:
      summary: Create an experiment
      description: |
        Create an experiment. Returns the ID of the newly created experiment resource.
      parameters:
        - name: experiment
          in: body
          description: The name, tags, and sample IDs to create the Experiment resource
          schema:
            type: object
            properties:
              name: 
                type: string
              tags:
                type: array
                items:
                  type: string
              samples:
                type: array
                items:
                  type: string
          required: true
      tags:
        - Experiments
      responses:
        201:
          description: The ID of the newly created Experiment resource
          schema:
            type: string
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - user
          - administrator

  /scores/record:
    post:
      summary: Record a score
      description: | 
        Record the score of an audio sample. Once a score is recorded it can neither be modified nor removed.
      parameters: 
        - name: scores
          in: body
          description: An array of Score resources
          schema:
            type: array
            items:
              $ref: '#/definitions/Score'
          required: true
      tags:
        - Scores
      responses:
        201:
          description: The ID of the score recorded
          schema:
            type: string
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - participant
  
  /participant/register:
    post:
      summary: Register a participant
      description: |
        Register a participant / new user from a client to the BirdFeed API. 
      parameters:
        - name: participant
          in: body
          description: Data for new participant resource
          schema:
            type: object
            properties:
              username:
                type: string
              password:
                type: string
          required: true
      tags:
        - Participants
      responses:
        201:
          description: The ID of the newly created Participant resource
          schema:
            type: string
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - birdcage:
          - client

definitions:
  Sample:
    type: object
    properties:
      id: 
        type: string
        description: 'Unique ID for each audio sample'
      name: 
        type: string
        description: 'Filename of audio sample'
      s3_url:
        type: string
        description: 'AWS link to location of audio sample'
      date_added:
        type: string
        format: date-time
        description: 'Timestamp of when sample was added'
      total_scores:
        type: integer
        description: 'Number of times that this sample has been graded in an experiment'
      avg_score:
        type: number
        description: 'Average linguistic quality of audio sample'
      expected_score:
        type: integer
        description: 'Expected linguistic quality score of audio sample'
      tags:
        type: array
        items:
          type: string
        description: 'Tags describing audio sample'
        maximum: 5
  Experiment:
    type: object
    properties:
      id: 
        type: string
        description: 'Unique ID for each experiment'
      name: 
        type: string
        description: 'User-defined name for experiment'
        maximum: 80
      date_created:
        type: string
        format: date-time
        description: 'Timestamp of when experiment was created'
      expiry_date: 
        type: string
        format: date-time
        description: 'Expiry date of experiment'
      tags:
        type: array
        items:
          type: string
        description: 'Tags describing the experiment'
      samples:
        type: array
        items: 
          type: string
        description: 'The audio samples used for scoring'
  Score:
    type: object
    properties:
      participant_id: 
        type: string
        description: 'The ID of the participant'
      sample_id:
        type: string
        description: 'The ID of the sample being scored'
      experiment_id:
        type: string
        description: 'The ID of the experiment the score belongs to'
      rating:
        type: number
        format: double
        maximum: 1
        minimum: 0
        description: 'The rating of the sample, 1 indicating perfect English speech, 0 indicating indiscernable speech'
  Participant:
    type: object
    properties:
      id:
        type: string
        description: 'The unique ID of the participant'
      username:
        type: string
        description: 'A unique user defined name'
      salt:
        type: string
        description: 'A salt of the plaintext password'
      date_created:
        type: string
        format: date-time
        description: 'Timestamp of when participant was created'
      quality:
        type: number
        format: double
        description: 'The quality of the participants ratings'
  Error:
    type: object
    properties:
      id: 
        type: string
        description: 'Unique ID for error message'
      message:
        type: string
        description: 'Details about the error encountered'
      path:
        type: string
        description: 'Request target at time of error'
      request:
        type: object
        description: 'The body of the request, if present'