swagger.yaml

openapi: 3.0.0
info:
  description: Sample API for Universal QR Codes
  version: 1.0.1
  title: Universal QR Code API
tags:
  - name: endpoint
    description: |
      ## What is this:
      URL to get the hostname from a QR code label - potentially hosted on a different server.
      This endpoint should also provide the vendor for the label,
      in order to assist in developers matching their API tokens to the correct endpoints.
      ## Usage:
      View a JSON schema of this inside the /wellknown/cannabis-api.schema.json
      The 'vendor' tag allows a developer to easily match their stored API keys to the endpoint.
      ## Additional Endpoints:
      If you would like additional endpoints to be stored in the cannabis-api.json file, you can specify them with fieldname-endpoint. For example 'distributor-endpoint' or 'pos-endpoint'. You should *always* have an endpoint entry, however.
  - name: product
    description: Information about product details like product name, description, doses, etc
  - name: batch
    description: Information about batch details like testing and THC content
  - name: case
    description: |
      Case matching input id - a case comes from a manufacturer and is a collection of items that are all the same. 
      It cannot contain different item types.
  - name: each
    description: Information and updating a serialized package - single unit of a product / batch
  - name: regulator
    description: Query for details about regulator tags
  - name: manifest
    description: |
      Get details from an order (probably from a distributor), describing child package to QR code url mappings
      The contents field contains an array of QR codes that represent all scanned cases or items,
      allowing a lookup on a per-vendor basis of the data about those cases or items.
      In order to use the cases in your system, just perform a lookup on the case information endpoint and get the each IDs -
      then use those to identify the scanned out QR codes.
      The regulatorEvent entry represents the transfer ID (if applicable). 
      Using the manifest endpoint, a retailer can scan a single barcode on a box and then use subsequent 
      API calls using the standard (to multiple vendors) to get information about the associated regulator tags and product information.
security:
  - Bearer Token:
      - write
servers:
  - url: https://qr.example.com/v1/uapi
    description: Server for your universal API

paths:
  /.well-known/cannabis-api.json:
    get:
      tags:
        - endpoint
      servers:
        - url: https://shortqrurl.com/
      responses:
        200:
          description: Successfully retrieved file
          content:
            application/json:
              schema:
                type: object
                required:
                  - endpoint
                  - vendor
                properties:
                  endpoint:
                    type: string
                    example: qr.example.com/uapi/v1/
                  path-components:
                    type: string
                    example: qr.example.com/i/:id
                  vendor:
                    type: string
                    enum: ["nabis", "lucidgreen", "chroma"]
                    example: nabis
                  "*-endpoint":
                    type: string
                    example: qr-poc.example.com/uapi/v1/
  /batch/{id}:
    get:
      tags:
        - batch
      parameters:
        - in: path
          name: id
          description: id of record to look up
          required: true
          schema:
            type: string
      responses:
        200:
          description: Get information about the batch from either a Collection id or an Each id
          content:
            application/json:
              schema:
                $ref: ./schemas/Batch.yaml

  /product/{id}:
    get:
      tags:
        - product
      parameters:
        - in: path
          name: id
          description: id of record to look up
          required: true
          schema:
            type: string
      responses:
        200:
          description: sku matching input identifier
          content:
            application/json:
              schema:
                $ref: ./schemas/Product.yaml

  /case/{id}:
    get:
      tags:
        - case
      parameters:
        - $ref: "#/components/parameters/pathId"
        - $ref: "#/components/parameters/excludeFields"
      responses:
        200:
          description: Case matching input Id
          content:
            application/json:
              schema:
                $ref: ./schemas/Case.yaml
    put:
      tags:
        - case
      parameters:
        - $ref: "#/components/parameters/pathId"
      requestBody:
        $ref: "#/components/requestBodies/regulatorBody"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./schemas/Case.yaml
  /each/{id}:
    get:
      tags:
        - each
      parameters:
        - $ref: "#/components/parameters/pathId"
        - $ref: "#/components/parameters/excludeFields"
      responses:
        200:
          description: Each matching input id
          content:
            application/json:
              schema:
                $ref: ./schemas/Each.yaml
    put:
      tags:
        - each
      parameters:
        - $ref: "#/components/parameters/pathId"
      requestBody:
        $ref: "#/components/requestBodies/regulatorBody"
      responses:
        200:
          description: Each matching input id
          content:
            application/json:
              schema:
                $ref: ./schemas/Each.yaml
  /regulator/{id}:
    get:
      tags:
        - regulator
      parameters:
        - $ref: "#/components/parameters/pathId"
      responses:
        200:
          $ref: "#/components/responses/eachesAndCasesResponse"
    put:
      tags:
        - regulator
      parameters:
        - $ref: "#/components/parameters/pathId"
      requestBody:
        $ref: "#/components/requestBodies/regulatorMultiputBody"
      responses:
        200:
          description: Returns the regulator event that was attached to these items, fails if the items are not all from the same parent
          content:
            application/json:
              schema:
                $ref: ./schemas/Regulator.yaml
        404:
          description: Returned if not all ids were able to be attached, this indicates an error in the tagging Flower"
          content:
            application/json:
              schema:
                type: object
                properties:
                  failures:
                    $ref: ./schemas/IdArray.yaml
  /manifest/{id}:
    get:
      tags:
        - manifest
      parameters:
        - $ref: "#/components/parameters/pathId"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./schemas/Manifest.yaml
              example:
                regulatorEvent:
                  id: "0003166342"
                  kind: manifest
                contents:
                  - "qr.example.com/i/1234"
                  - "qr-test.example.com/i/abcd"

components:
  securitySchemes:
    Bearer Token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Any users may generate a bearer API token from their account page on a respective labeling site.
        Tokens are only needed for write operations - all read operations can happen without authentication.
  schemas:
    $ref: schemas/_index.yaml
  parameters:
    pathId:
      in: path
      name: id
      description: id to look up
      required: true
      schema:
        type: string
    excludeFields:
      in: query
      name: excludedFields
      description: comma separated list of fields to exclude in the request body
      required: false
      schema:
        type: array
        example: "product,batch"
        items:
          type: string

  requestBodies:
    regulatorBody:
      description: Body for a put / post with regulator information
      content:
        application/json:
          schema:
            oneOf:
              - $ref: ./schemas/Regulator.yaml
    regulatorMultiputBody:
      description: Body for a request to put a regulator id on multiple items
      content:
        application/json:
          schema:
            type: object
            properties:
              ids:
                $ref: ./schemas/IdArray.yaml

  responses:
    eachesAndCasesResponse:
      description: Array of eaches, cases, and regualator events associated with a regulatorId
      content:
        application/json:
          schema:
            type: object
            properties:
              eaches:
                type: array
                items:
                  $ref: ./schemas/IdArray.yaml
              cases:
                type: array
                items:
                  $ref: ./schemas/IdArray.yaml
              regulatorEvents:
                type: array
                items:
                  $ref: ./schemas/Regulator.yaml