swagger.json

{
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "http"
  ],
  "swagger": "2.0",
  "info": {
    "description": "HTTP API for transcoding media files into different formats using pluggable\nproviders.\n\n## Currently supported providers\n\n+ [Amazon Elastic Transcoder](https://aws.amazon.com/elastictranscoder/)\n+ [Elemental Conductor](https://www.elementaltechnologies.com/products/elemental-conductor)\n+ [Encoding.com](http://api.encoding.com)\n+ [Zencoder](http://zencoder.com)",
    "title": "video-transcoding-api",
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.0"
  },
  "basePath": "/",
  "paths": {
    "/jobs": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Creates a new transcoding job.",
        "operationId": "newJob",
        "parameters": [
          {
            "name": "Payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/NewTranscodeJobInputPayload"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/job"
          },
          "400": {
            "$ref": "#/responses/invalidJob"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "description": "It also queries the provider to get the status of the job.",
        "tags": [
          "jobs"
        ],
        "summary": "Finds a trancode job using its ID.",
        "operationId": "getJob",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "JobID",
            "name": "jobId",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/jobStatus"
          },
          "404": {
            "$ref": "#/responses/jobNotFound"
          },
          "410": {
            "$ref": "#/responses/jobNotFoundInTheProvider"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/jobs/{jobId}/cancel": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Creates a new transcoding job.",
        "operationId": "cancelJob",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "JobID",
            "name": "jobId",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/jobStatus"
          },
          "404": {
            "$ref": "#/responses/jobNotFound"
          },
          "410": {
            "$ref": "#/responses/jobNotFoundInTheProvider"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/presetmaps": {
      "get": {
        "tags": [
          "presets"
        ],
        "summary": "List available presets on the API.",
        "operationId": "listPresetMaps",
        "responses": {
          "200": {
            "$ref": "#/responses/listPresetMaps"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      },
      "post": {
        "tags": [
          "presets"
        ],
        "summary": "Creates a new preset in the API.",
        "operationId": "newPreset",
        "parameters": [
          {
            "name": "Payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PresetMap"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/preset"
          },
          "400": {
            "$ref": "#/responses/invalidPreset"
          },
          "409": {
            "$ref": "#/responses/presetAlreadyExists"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/presetmaps/{name}": {
      "get": {
        "tags": [
          "presets"
        ],
        "summary": "Finds a preset using its name.",
        "operationId": "getPreset",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "Name",
            "name": "name",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/preset"
          },
          "404": {
            "$ref": "#/responses/presetNotFound"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      },
      "put": {
        "tags": [
          "presets"
        ],
        "summary": "Updates a presetmap using its name.",
        "operationId": "updatePreset",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "Name",
            "name": "name",
            "in": "path",
            "required": true
          },
          {
            "name": "Payload",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PresetMap"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/preset"
          },
          "400": {
            "$ref": "#/responses/invalidPreset"
          },
          "404": {
            "$ref": "#/responses/presetNotFound"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      },
      "delete": {
        "tags": [
          "presets"
        ],
        "summary": "Deletes a presetmap by name.",
        "operationId": "deletePresetMap",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "Name",
            "name": "name",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/emptyResponse"
          },
          "404": {
            "$ref": "#/responses/presetNotFound"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/presets": {
      "post": {
        "tags": [
          "presets"
        ],
        "summary": "Creates a new preset on given providers.",
        "operationId": "Output",
        "responses": {
          "200": {
            "$ref": "#/responses/newPresetOutputs"
          },
          "400": {
            "$ref": "#/responses/invalidPreset"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/presets/{name}": {
      "delete": {
        "tags": [
          "presets"
        ],
        "summary": "Deletes a preset by name.",
        "operationId": "deletePreset",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "Name",
            "name": "name",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/deletePresetOutputs"
          },
          "404": {
            "$ref": "#/responses/presetNotFound"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/providers": {
      "get": {
        "description": "Describe available providers in the API, including their name, capabilities\nand health state.",
        "tags": [
          "providers"
        ],
        "operationId": "listProviders",
        "responses": {
          "200": {
            "$ref": "#/responses/listProviders"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    },
    "/providers/{name}": {
      "get": {
        "description": "Describe available providers in the API, including their name, capabilities\nand health state.",
        "tags": [
          "providers"
        ],
        "operationId": "getProvider",
        "parameters": [
          {
            "type": "string",
            "x-go-name": "Name",
            "name": "name",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/responses/provider"
          },
          "404": {
            "$ref": "#/responses/providerNotFound"
          },
          "500": {
            "$ref": "#/responses/genericError"
          }
        }
      }
    }
  },
  "definitions": {
    "Capabilities": {
      "description": "Capabilities describes the available features in the provider. It specificie\nwhich input and output formats the provider supports, along with\nsupported destinations.",
      "type": "object",
      "properties": {
        "destinations": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-go-name": "Destinations"
        },
        "input": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-go-name": "InputFormats"
        },
        "output": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-go-name": "OutputFormats"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "Description": {
      "description": "It contains the name of the provider, along with its current heath status\nand its capabilities.",
      "type": "object",
      "title": "Description fully describes a provider.",
      "properties": {
        "capabilities": {
          "x-go-name": "Capabilities",
          "$ref": "#/definitions/Capabilities"
        },
        "enabled": {
          "type": "boolean",
          "x-go-name": "Enabled"
        },
        "health": {
          "x-go-name": "Health",
          "$ref": "#/definitions/Health"
        },
        "name": {
          "type": "string",
          "x-go-name": "Name"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "Duration": {
      "description": "A Duration represents the elapsed time between two instants\nas an int64 nanosecond count. The representation limits the\nlargest representable duration to approximately 290 years.",
      "type": "integer",
      "format": "int64",
      "x-go-package": "time"
    },
    "ErrorResponse": {
      "description": "ErrorResponse represents the basic error returned by the API on operation\nfailures.",
      "type": "object",
      "properties": {
        "error": {
          "description": "the error message\n\nin: body",
          "type": "string",
          "x-go-name": "Message"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/swagger"
    },
    "Health": {
      "description": "Health describes the current health status of the provider. If indicates\nwhether the provider is healthy or not, and if it's not healthy, it includes\na message explaining what's wrong.",
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "x-go-name": "Message"
        },
        "ok": {
          "type": "boolean",
          "x-go-name": "OK"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "JobOutput": {
      "type": "object",
      "title": "JobOutput represents information about a job output.",
      "properties": {
        "destination": {
          "type": "string",
          "x-go-name": "Destination"
        },
        "files": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/OutputFile"
          },
          "x-go-name": "Files"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "JobStatus": {
      "description": "JobStatus is the representation of the status as the provide sees it. The\nprovider is able to add customized information in the ProviderStatus field.",
      "type": "object",
      "properties": {
        "output": {
          "x-go-name": "Output",
          "$ref": "#/definitions/JobOutput"
        },
        "progress": {
          "type": "number",
          "format": "double",
          "x-go-name": "Progress"
        },
        "providerJobId": {
          "type": "string",
          "x-go-name": "ProviderJobID"
        },
        "providerName": {
          "type": "string",
          "x-go-name": "ProviderName"
        },
        "providerStatus": {
          "type": "object",
          "additionalProperties": {
            "type": "object"
          },
          "x-go-name": "ProviderStatus"
        },
        "sourceInfo": {
          "x-go-name": "SourceInfo",
          "$ref": "#/definitions/SourceInfo"
        },
        "status": {
          "x-go-name": "Status",
          "$ref": "#/definitions/Status"
        },
        "statusMessage": {
          "type": "string",
          "x-go-name": "StatusMessage"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "NewTranscodeJobInputPayload": {
      "description": "NewTranscodeJobInputPayload makes up the parameters available for\nspecifying a new transcoding job",
      "type": "object",
      "properties": {
        "outputs": {
          "description": "list of outputs in this job",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "fileName": {
                "type": "string",
                "x-go-name": "FileName"
              },
              "preset": {
                "type": "string",
                "x-go-name": "Preset"
              }
            }
          },
          "x-go-name": "Outputs"
        },
        "provider": {
          "description": "provider to use in this job",
          "type": "string",
          "x-go-name": "Provider"
        },
        "source": {
          "description": "source media for the transcoding job.",
          "type": "string",
          "x-go-name": "Source"
        },
        "streamingParams": {
          "description": "provider Adaptive Streaming parameters",
          "x-go-name": "StreamingParams",
          "$ref": "#/definitions/StreamingParams"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/service"
    },
    "OutputFile": {
      "type": "object",
      "title": "OutputFile represents an output file in a given job.",
      "properties": {
        "container": {
          "type": "string",
          "x-go-name": "Container"
        },
        "fileSize": {
          "type": "integer",
          "format": "int64",
          "x-go-name": "FileSize"
        },
        "height": {
          "type": "integer",
          "format": "int64",
          "x-go-name": "Height"
        },
        "path": {
          "type": "string",
          "x-go-name": "Path"
        },
        "videoCodec": {
          "type": "string",
          "x-go-name": "VideoCodec"
        },
        "width": {
          "type": "integer",
          "format": "int64",
          "x-go-name": "Width"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "OutputOptions": {
      "description": "This type includes only configuration parameters that are not defined in\nproviders (like the extension of the output file).",
      "type": "object",
      "title": "OutputOptions is the set of options for the output file.",
      "required": [
        "extension"
      ],
      "properties": {
        "extension": {
          "description": "extension for the output file, it's usually attached to the\ncontainer (for example, webm for VP, mp4 for MPEG-4 and ts for HLS).\n\nThe dot should not be part of the extension, i.e. use \"webm\" instead\nof \".webm\".",
          "type": "string",
          "x-go-name": "Extension"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/db"
    },
    "PartialJob": {
      "description": "PartialJob is the simple response given to an API\ncall that creates a new transcoding job",
      "type": "object",
      "properties": {
        "jobId": {
          "description": "unique identifier of the job",
          "type": "string",
          "uniqueItems": true,
          "x-go-name": "JobID"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/service"
    },
    "PresetMap": {
      "description": "Each presetmap is just an aggregator of provider presets, where each preset in\nthe API maps to a preset on each provider",
      "type": "object",
      "title": "PresetMap represents the preset that is persisted in the repository of the\nTranscoding API",
      "required": [
        "name",
        "providerMapping",
        "output"
      ],
      "properties": {
        "name": {
          "description": "name of the presetmap",
          "type": "string",
          "uniqueItems": true,
          "x-go-name": "Name"
        },
        "output": {
          "description": "set of options in the output file for this preset.",
          "x-go-name": "OutputOpts",
          "$ref": "#/definitions/OutputOptions"
        },
        "providerMapping": {
          "description": "mapping of provider name to provider's internal preset id.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "x-go-name": "ProviderMapping"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/db"
    },
    "SourceInfo": {
      "description": "SourceInfo contains information about media transcoded using the Transcoding\nAPI.",
      "type": "object",
      "properties": {
        "duration": {
          "description": "Duration of the media",
          "x-go-name": "Duration",
          "$ref": "#/definitions/Duration"
        },
        "height": {
          "description": "Dimension of the media, in pixels",
          "type": "integer",
          "format": "int64",
          "x-go-name": "Height"
        },
        "videoCodec": {
          "description": "Codec used for video medias",
          "type": "string",
          "x-go-name": "VideoCodec"
        },
        "width": {
          "type": "integer",
          "format": "int64",
          "x-go-name": "Width"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "Status": {
      "type": "string",
      "title": "Status is the status of a transcoding job.",
      "x-go-package": "github.com/NYTimes/video-transcoding-api/provider"
    },
    "StreamingParams": {
      "description": "StreamingParams represents the params necessary to create Adaptive Streaming jobs",
      "type": "object",
      "required": [
        "segmentDuration",
        "protocol",
        "playlistFileName"
      ],
      "properties": {
        "playlistFileName": {
          "description": "the playlist file name",
          "type": "string",
          "x-go-name": "PlaylistFileName"
        },
        "protocol": {
          "description": "the protocol name (hls or dash)",
          "type": "string",
          "x-go-name": "Protocol"
        },
        "segmentDuration": {
          "description": "duration of the segment",
          "type": "integer",
          "format": "uint64",
          "x-go-name": "SegmentDuration"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/db"
    },
    "deletePresetOutput": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "x-go-name": "Error"
        },
        "presetId": {
          "type": "string",
          "x-go-name": "PresetID"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/service"
    },
    "newPresetOutput": {
      "type": "object",
      "properties": {
        "Error": {
          "type": "string"
        },
        "PresetID": {
          "type": "string"
        }
      },
      "x-go-package": "github.com/NYTimes/video-transcoding-api/service"
    }
  },
  "responses": {
    "deletePresetOutputs": {
      "description": "list of the results of the attempt to delete a preset\nin each provider.",
      "schema": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/definitions/deletePresetOutput"
        }
      },
      "headers": {
        "presetMap": {
          "type": "string"
        }
      }
    },
    "emptyResponse": {
      "description": "emptyResponse represents an empty response returned by the API, it's\ncomposed only by the HTTP status code."
    },
    "genericError": {
      "description": "ErrorResponse represents the basic error returned by the API on operation\nfailures."
    },
    "invalidJob": {
      "description": "error returned when the given job data is not valid.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "invalidPreset": {
      "description": "error returned when the given preset data is not valid.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "job": {
      "description": "JSON-encoded version of the Job, includes only the id of the job, that can\nbe used for querying the current status of the job.",
      "schema": {
        "$ref": "#/definitions/PartialJob"
      }
    },
    "jobNotFound": {
      "description": "error returned the given job id could not be found on the API.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "jobNotFoundInTheProvider": {
      "description": "error returned when the given job id could not be found on the underlying\nprovider.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "jobStatus": {
      "description": "JSON-encoded JobStatus, containing status information given by the\nunderlying provider.",
      "schema": {
        "$ref": "#/definitions/JobStatus"
      }
    },
    "listPresetMaps": {
      "description": "response for the listPresetMaps operation. It's actually a JSON-encoded object\ninstead of an array, in the format `presetName: presetObject`",
      "schema": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/definitions/PresetMap"
        }
      }
    },
    "listProviders": {
      "description": "response for the listProviders operation. Contains the list of providers\nalphabetically ordered.",
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "newPresetOutputs": {
      "description": "list of the results of the attempt to create a preset\nin each provider.",
      "schema": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/definitions/newPresetOutput"
        }
      },
      "headers": {
        "PresetMap": {
          "type": "string"
        }
      }
    },
    "preset": {
      "description": "JSON-encoded preset returned on the newPreset and getPreset operations.",
      "schema": {
        "$ref": "#/definitions/PresetMap"
      }
    },
    "presetAlreadyExists": {
      "description": "error returned when trying to create a new preset using a name that is\nalready in-use.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "presetNotFound": {
      "description": "error returned when the given preset name is not found on the API (either on\ngetPreset or deletePreset operations).",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    },
    "provider": {
      "description": "response for the getProvider operation.",
      "schema": {
        "$ref": "#/definitions/Description"
      }
    },
    "providerNotFound": {
      "description": "error returned when the given provider name is not found in the API.",
      "schema": {
        "$ref": "#/definitions/ErrorResponse"
      }
    }
  }
}