swagger.yaml

swagger: "2.0"
info:
  version: 0.1.0
  title: TraxAir Test API
host: api.trax-air.com
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
paths:
  /track:
    get:
      tags:
        - track
      summary: "Retrieve all `Track` objects.\n"
      operationId: listTracks
      parameters:
        - $ref: "#/parameters/Limit"
        - $ref: "#/parameters/Offset"
      responses:
        "200":
          description: Successful response
          schema:
            title: ArrayOfTracks
            type: array
            items:
              $ref: "#/definitions/Track"
    post:
      tags:
        - track
      summary: "Creates a new `Track` object."
      operationId: addTrack
      parameters:
        - name: track
          in: body
          description: Track to add
          required: true
          schema:
            $ref: "#/definitions/Track"
      responses:
        "201":
          description: Track creation was successful
          schema:
            $ref: "#/definitions/Track"
  "/track/{trackId}":
    get:
      tags:
        - track
      summary: "Retrieve a `Track` object.\n"
      operationId: getTrack
      parameters:
        - name: trackId
          in: path
          description: the identifier of the track
          required: true
          type: integer
          format: int32
      responses:
        "200":
          description: Successful response
          schema:
            $ref: "#/definitions/Track"
  /identify/tracklist:
    post:
      tags:
        - identification
      summary: "Creates a `TracklistIdentification` object. Also creates a `TracklistIdentificationRun` numbered 0."
      operationId: tracklistIdentification
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          description: File to upload and analyze
          type: file
      responses:
        "201":
          description: Tracklist identification creation was successful
          schema:
            $ref: "#/definitions/TrackIdentification"
        "400":
          description: "Invalid input. You have to either set a file or an url, but not both or neither one."
  "/identify/tracklist/{identificationId}":
    get:
      tags:
        - identification
      summary: "Retrieve a `TracklistIdentification` object."
      operationId: getTracklistIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the tracklist identification
          type: string
      responses:
        "200":
          description: Successful
          schema:
            $ref: "#/definitions/TracklistIdentification"
    post:
      tags:
        - identification
      summary: "Creates a `TracklistIdentificationRun` object. This reruns the identification of the provided file or url."
      operationId: rerunTrackIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the tracklist identification
          type: string
      responses:
        "201":
          description: Successful
          schema:
            $ref: "#/definitions/TracklistIdentificationRun"
    put:
      tags:
        - identification
      summary: "Modify the content of a `TracklistIdentification` object."
      operationId: changeTracklistIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the tracklist identification
          type: string
        - name: body
          in: body
          description: The content to change. Can cover only parts of an object.
          schema:
            $ref: "#/definitions/TracklistIdentification"
      responses:
        "204":
          description: Successfully updated
        "405":
          description: Invalid input
  "/identify/tracklist/{identificationId}/{runNumber}":
    get:
      tags:
        - identification
      summary: "Retrieve a `TracklistIdentificationRun` object."
      operationId: getTracklistIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the tracklist identification
          type: string
        - name: runNumber
          in: path
          required: true
          description: The number of the tracklist identification run to retrieve
          type: string
      responses:
        "200":
          description: Successful
          schema:
            $ref: "#/definitions/TracklistIdentificationRun"
  /identify/track:
    post:
      tags:
        - identification
      summary: Identify a track from an URL or from an uploaded file.
      operationId: trackIdentification
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          description: File to upload and analyze
          type: file
      responses:
        "201":
          description: Track identification creation was successful
          schema:
            $ref: "#/definitions/TrackIdentification"
        "400":
          description: "Invalid input. You have to either set a file or an url, but not both or neither one."
  "/identify/track/{identificationId}":
    get:
      tags:
        - identification
      summary: Get a track identification.
      operationId: getTrackIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the track identification
          type: string
      responses:
        "200":
          description: Successful
          schema:
            $ref: "#/definitions/TrackIdentification"
    post:
      tags:
        - track
        - identification
      summary: Creates another run for a track identification.
      operationId: rerunTrackIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the track identification
          type: string
      responses:
        "201":
          description: Successful
          schema:
            $ref: "#/definitions/TrackIdentificationRun"
    put:
      tags:
        - identification
      summary: Modify the content of a track identification
      operationId: changeTrackIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the track identification
          type: string
        - name: body
          in: body
          description: The content to change. Can cover only parts of an object.
          schema:
            $ref: "#/definitions/TrackIdentification"
      responses:
        "204":
          description: Successfully updated
        "400":
          description: Invalid input
  "/identify/track/{identificationId}/{runNumber}":
    get:
      tags:
        - identification
      summary: "Retrieve a `TrackIdentificationRun` object."
      operationId: getTrackIdentification
      parameters:
        - name: identificationId
          in: path
          required: true
          description: The id of the track identification
          type: string
        - name: runNumber
          in: path
          required: true
          description: The number of the track identification run to retrieve
          type: string
      responses:
        "200":
          description: Successful
          schema:
            $ref: "#/definitions/TrackIdentificationRun"
  /me/billing:
    get:
      tags:
        - me
      summary: Retrieve the current and past billing information.
      operationId: myBills
      responses:
        "200":
          description: Successful
          schema:
            type: array
            items:
              $ref: "#/definitions/Bills"
  /me/callbacks:
    get:
      tags:
        - me
      summary: "Retrieve the callbacks that you set up to be notified of changes in tracklist or track identification, or track territory."
      operationId: myCallbacks
      responses:
        "200":
          description: Successful
          schema:
            $ref: "#/definitions/Callbacks"
    put:
      tags:
        - me
      summary: Update your callbacks
      operationId: changeCallbacks
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: callbackTrackIdentification
          description: Update callbackTrackIdentification
          type: string
        - in: formData
          name: callbackTracklistIdentification
          description: Update callbackTracklistIdentification
          type: string
        - in: formData
          name: callbackTrackTerritoryChange
          description: Update callbackTrackTerritoryChange
          type: string
      responses:
        "204":
          description: Successfully updated
        "405":
          description: Invalid input
definitions:
  MetadataIdentification:
    title: MetadataIdentification
    type: object
    properties:
      sourceUrl:
        type: string
      curator:
        type: string
      territoryCode:
        type: string
      latitude:
        type: string
      longitude:
        type: string
      genre:
        type: string
      type:
        type: string
      source:
        type: string
      date:
        type: string
        format: date
      additionalData:
        type: string
  TracklistIdentification:
    title: TracklistIdentification
    type: object
    properties:
      id:
        type: string
        readOnly: true
      metadata:
        $ref: "#/definitions/MetadataIdentification"
      url:
        type: string
        readOnly: true
      filename:
        type: string
        readOnly: true
      identifications:
        type: array
        items:
          $ref: "#/definitions/TracklistIdentificationRun"
  TracklistIdentificationRun:
    title: TracklistIdentificationRun
    type: object
    properties:
      number:
        type: integer
        readOnly: true
      params:
        $ref: "#/definitions/RunParams"
      date:
        type: string
        format: date
      done:
        type: boolean
      track:
        $ref: "#/definitions/Tracklist"
  RunParams:
    title: RunParams
    type: array
    items:
      type: object
      properties:
        start:
          type: integer
          minimum: 0
        end:
          type: integer
          minimum: 0
  Tracklist:
    title: Tracklist
    type: object
    properties:
      id:
        type: string
        readOnly: true
      segments:
        type: array
        items:
          type: object
          properties:
            track:
              $ref: "#/definitions/Track"
            start:
              type: integer
              minimum: 0
            end:
              type: integer
              minimum: 0
  TrackIdentification:
    title: TrackIdentification
    type: object
    properties:
      id:
        type: string
        readOnly: true
      metadata:
        $ref: "#/definitions/MetadataIdentification"
      url:
        type: string
        readOnly: true
      filename:
        type: string
        readOnly: true
      runs:
        type: array
        items:
          $ref: "#/definitions/TrackIdentificationRun"
  TrackIdentificationRun:
    title: TrackIdentificationRun
    type: object
    properties:
      number:
        type: integer
        readOnly: true
      date:
        type: string
        format: date
      track:
        $ref: "#/definitions/Track"
  Track:
    title: Track
    type: object
    properties:
      id:
        type: string
        readOnly: true
      ISRC:
        type: string
        readOnly: true
      title:
        type: string
      genre:
        type: string
      artists:
        type: array
        items:
          $ref: "#/definitions/Artist"
      release:
        $ref: "#/definitions/Release"
      UPC:
        type: string
      duration:
        type: integer
      territory:
        type: string
      releaseDate:
        type: string
        format: date
  Artist:
    title: Artist
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      role:
        type: string
  Release:
    title: Release
    type: object
    properties:
      id:
        type: string
      title:
        type: string
      label:
        type: string
      publisher:
        type: string
      cover:
        type: string
  Callbacks:
    title: Callbacks
    type: object
    properties:
      callbackTrackIdentification:
        type: string
      callbackTracklistIdentification:
        type: string
      callbackTrackTerritoryChange:
        type: string
  Bills:
    title: Bills
    type: object
    properties:
      date:
        type: string
        format: date
      hoursAnalyzed:
        type: integer
      price:
        type: number

parameters:
  Limit: 
    name: limit
    in: query
    description: maximum number of results to return
    required: false
    type: integer
    format: int32
    maximum: 1000
    minimum: 10
    default: 10
  Offset: 
    name: offset
    in: query
    description: offset on the results to return
    required: false
    type: integer
    format: int32
    minimum: 0
    default: 0