swagger.json

{
  "basePath": "/",
  "paths": {
    "/barcode/0.1.0/reader/{jobid}": {
      "get": {
        "summary": "Job definition and state",
        "security": [{"oauth2schema": ["global"]}],
        "produces": ["application/json;charset=UTF-8"],
        "description": "Get the ReadResult response , job definition and current state. Please note that you can differentiate completion based on http response status",
        "operationId": "getJob",
        "responses": {
          "200": {
            "schema": {"$ref": "#/definitions/ReaderResultJobResponse"},
            "description": "Read job returned and Job is done or in error"
          },
          "202": {
            "schema": {"$ref": "#/definitions/ReaderJobResponse"},
            "description": "Read job returned and Job is still processing"
          },
          "404": {
            "schema": {"$ref": "#/definitions/ErrorResponse"},
            "description": "Invalid job id"
          }
        },
        "parameters": [{
          "in": "path",
          "name": "jobid",
          "description": "jobid",
          "type": "string",
          "required": true
        }],
        "tags": ["BarcodeReader"],
        "consumes": ["application/json"]
      },
      "delete": {
        "summary": "Delete a job manually",
        "security": [{"oauth2schema": ["global"]}],
        "produces": ["application/json;charset=UTF-8"],
        "description": "Delete the Job and all related files",
        "operationId": "deleteJob",
        "responses": {
          "200": {
            "schema": {"$ref": "#/definitions/ReaderJobResponse"},
            "description": "Job is deleted"
          },
          "400": {
            "schema": {"$ref": "#/definitions/ErrorResponse"},
            "description": "Could not delete all parts"
          },
          "404": {
            "schema": {"$ref": "#/definitions/ErrorResponse"},
            "description": "Invalid job id"
          }
        },
        "parameters": [{
          "in": "path",
          "name": "jobid",
          "description": "jobid",
          "type": "string",
          "required": true
        }],
        "tags": ["BarcodeReader"],
        "consumes": ["application/json"]
      },
      "put": {
        "summary": "Submit job for reading",
        "security": [{"oauth2schema": ["global"]}],
        "produces": ["application/json;charset=UTF-8"],
        "description": "Starts the barcode detection of the uploaded files, using the supplied settings associated with the job in the request body. You can only submit the job after a new Job is created with status INPUTS_UPLOADED or resubmit an existing Job with status ERROR. In all cases the jobId in the path must match the jobId in the request",
        "operationId": "submitJob",
        "responses": {
          "200": {
            "schema": {"$ref": "#/definitions/ReaderJobResponse"},
            "description": "Read job submitted"
          },
          "400": {
            "schema": {"$ref": "#/definitions/ErrorResponse"},
            "description": "Resubmitted job not allowed because the job is currently processing or already processed and had status DONE"
          },
          "404": {
            "schema": {"$ref": "#/definitions/ErrorResponse"},
            "description": "Invalid job id"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "jobid",
            "description": "jobid",
            "type": "string",
            "required": true
          },
          {
            "schema": {"$ref": "#/definitions/ReaderJob"},
            "in": "body",
            "name": "job",
            "description": "jobEntity",
            "required": true
          }
        ],
        "tags": ["BarcodeReader"],
        "consumes": ["application/json;charset=UTF-8"]
      }
    },
    "/barcode/0.1.0/reader": {"post": {
      "summary": "Upload the file",
      "security": [{"oauth2schema": ["global"]}],
      "produces": ["application/json;charset=UTF-8"],
      "description": "Upload the  image.",
      "operationId": "uploadFile",
      "responses": {"200": {
        "schema": {"$ref": "#/definitions/ReaderJobResponse"},
        "description": "File uploaded successfully. Reader job created but not started yet"
      }},
      "parameters": [{
        "in": "formData",
        "name": "stream",
        "description": "The first image.",
        "type": "file",
        "required": true
      }],
      "tags": ["BarcodeReader"],
      "consumes": ["multipart/form-data"]
    }}
  },
  "host": "gw.api.cloud.sphereon.com",
  "schemes": ["https"],
  "securityDefinitions": {"oauth2schema": {
    "tokenUrl": "https://gw.api.cloud.sphereon.com/token",
    "scopes": {"global": "accessEverything"},
    "type": "oauth2",
    "flow": "application"
  }},
  "definitions": {
    "ReaderJobSettings": {
      "description": "Barcode reader settings",
      "type": "object",
      "properties": {
        "lifecycle": {"$ref": "#/definitions/Lifecycle"},
        "outputFileName": {"type": "string"},
        "engine": {
          "type": "string",
          "enum": [
            "BASIC",
            "ADVANCED",
            "PREMIUM"
          ]
        },
        "outputFileFormat": {
          "type": "string",
          "enum": ["JSON"]
        }
      }
    },
    "Barcode": {
      "type": "object",
      "properties": {
        "confidenceLevel": {
          "format": "double",
          "description": "The confidence level of the barcode",
          "readOnly": true,
          "type": "number"
        },
        "pageNo": {
          "format": "int32",
          "description": "The number of the page the barcode is on",
          "readOnly": true,
          "type": "integer"
        },
        "coordinates": {
          "description": "The coordinates of the barcode. There are usually 2 coordinates, with an x and y value and an anchor.",
          "readOnly": true,
          "type": "array",
          "items": {"$ref": "#/definitions/BarcodeCoordinate"}
        },
        "text": {
          "description": "The text of the barcode",
          "readOnly": true,
          "type": "string"
        },
        "type": {
          "description": "The type of the barcode",
          "readOnly": true,
          "type": "string",
          "enum": [
            "AZTEC",
            "CODABAR",
            "CODE_39",
            "CODE_39_EXTENDED",
            "CODE_93",
            "CODE_128",
            "DATA_MATRIX",
            "EAN_8",
            "EAN_13",
            "ITF",
            "MAXICODE",
            "PDF_417",
            "QR_CODE",
            "RSS_14",
            "RSS_EXPANDED",
            "UPC_A",
            "UPC_E",
            "UPC_EAN_EXTENSION",
            "IDENTCODE",
            "INTERLEAVED25"
          ]
        }
      }
    },
    "Lifecycle": {
      "description": "Lifecycle settings. When no lifecycle settings are supplied, the job and files will be deleted directly after retrieval of the file",
      "type": "object",
      "properties": {
        "actionTime": {
          "format": "date-time",
          "description": "The time at which the job and files will be deleted, regardless of whether it has been retrieved or not. Maximal time is 1 day from job creation",
          "type": "string"
        },
        "action": {
          "type": "string",
          "enum": ["DELETE"]
        },
        "type": {
          "type": "string",
          "enum": [
            "RETRIEVAL",
            "TIME"
          ]
        }
      }
    },
    "Error": {
      "description": "An error",
      "type": "object",
      "required": [
        "code",
        "level",
        "message"
      ],
      "properties": {
        "code": {"type": "string"},
        "level": {
          "type": "string",
          "enum": [
            "INFO",
            "WARNING",
            "FATAL"
          ]
        },
        "cause": {"$ref": "#/definitions/Error"},
        "message": {"type": "string"}
      }
    },
    "ReaderJobResponse": {
      "description": "The Reader job response. Has access to the job, it' s settings as well as engine tasks",
      "type": "object",
      "required": [
        "inputs",
        "status"
      ],
      "properties": {
        "completionTime": {
          "format": "date-time",
          "description": "The completion date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "jobId": {"type": "string"},
        "creationTime": {
          "format": "date-time",
          "description": "The creation date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "inputs": {
          "description": "The original input files. Currently supported inputs are: tif files",
          "type": "array",
          "items": {"type": "string"}
        },
        "updateTime": {
          "format": "date-time",
          "description": "The last update date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "job": {"$ref": "#/definitions/ReaderJob"},
        "statusMessage": {
          "description": "A status message, which can be informational, warning or error. A message here does not indicate an error perse",
          "readOnly": true,
          "type": "string"
        },
        "tasks": {
          "description": "The server supplied reader task(s)",
          "readOnly": true,
          "type": "array",
          "items": {"$ref": "#/definitions/ReaderEngineTask"}
        },
        "queueTime": {
          "format": "date-time",
          "description": "The reader queue date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "status": {
          "description": "The status of the job",
          "readOnly": true,
          "type": "string",
          "enum": [
            "INPUTS_UPLOADED",
            "PROCESSING",
            "DONE",
            "ERROR",
            "DELETED"
          ]
        }
      }
    },
    "ReaderEngineTask": {
      "type": "object",
      "properties": {
        "jobId": {
          "description": "The current job Id",
          "readOnly": true,
          "type": "string"
        },
        "queueId": {
          "description": "The queue Id provided by a backend system",
          "readOnly": true,
          "type": "string"
        },
        "engine": {
          "description": "The Engine being used",
          "readOnly": true,
          "type": "string",
          "enum": [
            "ADVANCED",
            "PREMIUM",
            "BASIC"
          ]
        },
        "inputs": {
          "description": "The names of the supplied files/inputs",
          "readOnly": true,
          "type": "array",
          "items": {"type": "string"}
        },
        "documentId": {
          "description": "The document Id provided by a backend system",
          "readOnly": true,
          "type": "string"
        },
        "url": {
          "description": "The URL on the bucketstore for the Barcode file. Only available once the status is DONE",
          "readOnly": true,
          "type": "string"
        },
        "status": {
          "description": "The status of the Reader task itself",
          "readOnly": true,
          "type": "string",
          "enum": [
            "REQUESTED",
            "QUEUED",
            "PROCESSING",
            "DONE",
            "ERROR"
          ]
        }
      }
    },
    "ReaderResultJobResponse": {
      "description": "The Reader job response. Has access to the job, it' s settings as well as engine tasks",
      "type": "object",
      "required": [
        "barcodes",
        "inputs",
        "status"
      ],
      "properties": {
        "completionTime": {
          "format": "date-time",
          "description": "The completion date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "jobId": {"type": "string"},
        "creationTime": {
          "format": "date-time",
          "description": "The creation date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "inputs": {
          "description": "The original input files. Currently supported inputs are: tif files",
          "type": "array",
          "items": {"type": "string"}
        },
        "updateTime": {
          "format": "date-time",
          "description": "The last update date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "barcodes": {
          "description": "The returned barcodes",
          "readOnly": true,
          "type": "array",
          "items": {"$ref": "#/definitions/Barcode"}
        },
        "job": {"$ref": "#/definitions/ReaderJob"},
        "statusMessage": {
          "description": "A status message, which can be informational, warning or error. A message here does not indicate an error perse",
          "readOnly": true,
          "type": "string"
        },
        "tasks": {
          "description": "The server supplied reader task(s)",
          "readOnly": true,
          "type": "array",
          "items": {"$ref": "#/definitions/ReaderEngineTask"}
        },
        "queueTime": {
          "format": "date-time",
          "description": "The reader queue date/time of this job in ISO 8601 format",
          "readOnly": true,
          "type": "string"
        },
        "status": {
          "description": "The status of the job",
          "readOnly": true,
          "type": "string",
          "enum": [
            "INPUTS_UPLOADED",
            "PROCESSING",
            "DONE",
            "ERROR",
            "DELETED"
          ]
        }
      }
    },
    "ReaderJob": {
      "description": "The Detector job. Has access to the job settings.",
      "type": "object",
      "required": ["jobId"],
      "properties": {
        "jobId": {
          "description": "The server generated job jobId. This jobId is checked against the jobId in the request path on every invocation",
          "type": "string"
        },
        "settings": {"$ref": "#/definitions/ReaderJobSettings"}
      }
    },
    "BarcodeCoordinate": {
      "type": "object",
      "properties": {
        "anchor": {
          "description": "The anchor to which the positions apply",
          "readOnly": true,
          "type": "string",
          "enum": [
            "LEFT_TOP",
            "RIGHT_TOP",
            "LEFT_BOTTOM",
            "RIGHT_BOTTOM",
            "CENTER",
            "UNKNOWN"
          ]
        },
        "x": {
          "format": "int32",
          "description": "The X position",
          "readOnly": true,
          "type": "integer"
        },
        "y": {
          "format": "int32",
          "description": "The Y position",
          "readOnly": true,
          "type": "integer"
        }
      }
    },
    "ErrorResponse": {
      "description": "The error response",
      "type": "object",
      "properties": {"errors": {
        "type": "array",
        "items": {"$ref": "#/definitions/Error"}
      }}
    }
  },
  "swagger": "2.0",
  "info": {
    "license": {
      "name": "Apache License Version 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    },
    "contact": {
      "name": "Sphereon DevOps Team",
      "url": "https://sphereon.com",
      "email": "dev@sphereon.com"
    },
    "description": "<b>The Barcode Reader API '/reader' reads barcodes from image files and returns the barcode data as JSON files.<\/b>\r\n\r\nThe flow is generally as follows:\r\n1. First upload an image using the /reader POST endpoint. You will get back a job response that contains a job with its associated settings.\r\n2. Start the job from a PUT request to the /reader/{jobid} endpoint, with the Job and Settings JSON as request body. The barcode detection will now start.\r\n3. Check the job status from the /reader/{jobid} GET endpoint until the status has changed to DONE or ERROR. Messaging using a websocket will be available as an alternative in a future version\r\n4. Retrieve the JSON file using the /reader/{jobid}/stream GET endpoint. This will return the JSON file only when the status is DONE. In other cases it will return the Job Response JSON (with http code 202 instead of 200)\r\n\r\n\r\n<b>Interactive testing: <\/b>A web based test console is available in the <a href=\"https://store.sphereon.com\">Sphereon API Store<\/a>",
    "termsOfService": "https://sphereon.com",
    "title": "Barcode",
    "version": "0.1.0"
  },
  "tags": [{
    "name": "BarcodeReader",
    "description": "Barcode reader API"
  }]
}