openapi.yaml

openapi: 3.1.0
info:
  title: The Speakeasy Bar
  version: 1.0.0
  summary: A bar that serves drinks.
  description: A secret underground bar that serves drinks to those in the know.
  contact:
    name: Speakeasy Support
    url: https://support.speakeasy.bar
    email: support@speakeasy.bar
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://speakeasy.bar/terms
externalDocs:
  url: https://docs.speakeasy.bar
  description: The Speakeasy Bar Documentation.
servers:
  - url: https://speakeasy.bar
    description: The production server.
    x-speakeasy-server-id: prod
  - url: https://staging.speakeasy.bar
    description: The staging server.
    x-speakeasy-server-id: staging
  - url: https://{organization}.{environment}.speakeasy.bar
    description: A per-organization and per-environment API.
    x-speakeasy-server-id: customer
    variables:
      organization:
        description: The organization name. Defaults to a generic organization.
        default: api
      environment:
        description: The environment name. Defaults to the production environment.
        default: prod
        enum:
          - prod
          - staging
          - dev
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500        # 500 milliseconds
    maxInterval: 60000          # 60 seconds
    maxElapsedTime: 3600000     # 5 minutes
    exponent: 1.5
  statusCodes:
    - 5XX
  retryConnectionErrors: true
  
x-speakeasy-pagination:
  type: offsetLimit
  inputs:
    - name: page
      in: parameters
      type: page
  outputs:
    results: $.data.resultArray
security:
  - apiKey: []
  - clientCredentials:
    - read:basic
tags:
  - name: drinks
    description: The drinks endpoints.
  - name: ingredients
    description: The ingredients endpoints.
  - name: orders
    description: The orders endpoints.
  - name: authentication
    description: The authentication endpoints.
  - name: config

paths:

  x-speakeasy-errors:
    statusCodes: # Defines status codes to handle as errors for all operations
      - 4XX # Wildcard to handle all status codes in the 400-499 range
      - 5XX
  /authenticate:
    post:
      operationId: authenticate
      summary: Authenticate with the API by providing a username and password.
      security: []
      tags:
        - authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: The api key to use for authenticated endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
        "401":
          description: Invalid credentials provided.
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

  /drinks:
    get:
      x-speakeasy-usage-example: true
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security:
        - clientCredentials:
          - read:drinks
      tags:
        - drinks
      parameters:
        - name: drinkType
          in: query
          description: The type of drink to filter by. If not provided all drinks will be returned.
          required: false
          schema:
            $ref: "#/components/schemas/DrinkType"
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

  /drink/{name}: #TODO: this should be by product code and we should have search by name
    get:
      operationId: getDrink
      summary: Get a drink.
      description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - drinks
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A drink.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

  /ingredients:
    get:
      operationId: listIngredients
      summary: Get a list of ingredients.
      description: Get a list of ingredients, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - ingredients
      parameters:
        - name: page
          in: query
          schema:
            type: integer
          required: true
        - name: ingredients
          in: query
          description: A list of ingredients to filter by. If not provided all ingredients will be returned.
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: A list of ingredients.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      resultArray:
                        type: array
                        items:
                          type: integer
                    required:
                      - resultArray
                  
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

  /order:
    post:
      operationId: createOrder
      x-speakeasy-usage-example: true
      summary: Create an order.
      description: Create an order for a drink.
      tags:
        - orders
      parameters:
        - name: callback_url
          in: query
          description: The url to call when the order is updated.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Order"
      responses:
        "200":
          description: The order was created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"
      callbacks:
        orderUpdate:
          "{$request.query.callback_url}":
            post:
              summary: Receive order updates.
              description: Receive order updates from the supplier, this will be called whenever the status of an order changes.
              tags:
                - orders
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        order:
                          $ref: "#/components/schemas/Order"
              responses:
                "200":
                  description: The order update was received successfully.
                "5XX":
                  $ref: "#/components/responses/APIError"
                default:
                  $ref: "#/components/responses/UnknownError"
  /webhooks/subscribe:
    post:
      operationId: subscribeToWebhooks
      summary: Subscribe to webhooks.
      description: Subscribe to webhooks.
      tags:
        - config
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  webhook:
                    type: string
                    enum:
                      - stockUpdate
      responses:
        "200":
          description: The webhook was subscribed to successfully.
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"
webhooks:
  stockUpdate:
    post:
      summary: Receive stock updates.
      description: Receive stock updates from the bar, this will be called whenever the stock levels of a drink or ingredient changes.
      tags:
        - drinks
        - ingredients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                drink:
                  $ref: "#/components/schemas/Drink"
                ingredient:
                  $ref: "#/components/schemas/Ingredient"
      responses:
        "200":
          description: The stock update was received successfully.
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"
components:
  schemas:
    APIError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    Drink:
      type: object
      properties:
        name:
          description: The name of the drink.
          type: string
          examples:
            - Old Fashioned
            - Manhattan
            - Negroni
        type:
          $ref: "#/components/schemas/DrinkType"
        price:
          description: The price of one unit of the drink in US cents.
          type: number
          examples:
            - 1000 # $10.00
            - 1200 # $12.00
            - 1500 # $15.00
        stock:
          description: The number of units of the drink in stock, only available when authenticated.
          type: integer
          readOnly: true
        productCode:
          description: The product code of the drink, only available when authenticated.
          type: string
          examples:
            - "AC-A2DF3"
            - "NAC-3F2D1"
            - "APM-1F2D3"
      required:
        - name
        - price
    DrinkType:
      description: The type of drink.
      type: string
      enum:
        - cocktail
        - non-alcoholic
        - beer
        - wine
        - spirit
        - other
    Ingredient:
      type: object
      properties:
        name:
          description: The name of the ingredient.
          type: string
          examples:
            - Sugar Syrup
            - Angostura Bitters
            - Orange Peel
        type:
          $ref: "#/components/schemas/IngredientType"
        stock:
          description: The number of units of the ingredient in stock, only available when authenticated.
          type: integer
          examples:
            - 10
            - 5
            - 0
          readOnly: true
        productCode:
          description: The product code of the ingredient, only available when authenticated.
          type: string
          examples:
            - "AC-A2DF3"
            - "NAC-3F2D1"
            - "APM-1F2D3"
      required:
        - name
        - type
    IngredientType:
      description: The type of ingredient.
      type: string
      enum:
        - fresh
        - long-life
        - packaged
    Order:
      description: An order for a drink or ingredient.
      type: object
      properties:
        type:
          $ref: "#/components/schemas/OrderType"
        productCode:
          description: The product code of the drink or ingredient.
          type: string
          examples:
            - "AC-A2DF3"
            - "NAC-3F2D1"
            - "APM-1F2D3"
        quantity:
          description: The number of units of the drink or ingredient to order.
          type: integer
          minimum: 1
        status:
          description: The status of the order.
          type: string
          enum:
            - pending
            - processing
            - complete
          readOnly: true
      required:
        - type
        - productCode
        - quantity
        - status
    OrderType:
      description: The type of order.
      type: string
      enum:
        - drink
        - ingredient
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://speakeasy.bar/oauth2/token/
          scopes: {}
  responses:
    APIError:
      description: An error occurred interacting with the API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    UnknownError:
      description: An unknown error occurred interacting with the API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"