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
security:
  - apiKey: []
  - bearerAuth: []
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: login
      summary: Authenticate with the API by providing a username and password.
      security:
        - basicHttp: []
      tags:
        - authentication
      x-speakeasy-usage-example:
        title: "Sign in"
        description: |-
          First you need to send an authentication request to the API by providing your username and password.
          In the request body, you should specify the type of token you would like to receive: API key or JSON Web Token.
          If your credentials are valid, you will receive a token in the response object: `res.object.token: str`.
        position: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - apiKey
                    - JWT
      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:
      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.
      x-speakeasy-usage-example:
        title: "Browse available drinks"
        description: |-
          Once you are authenticated, you can use the token you received for all other authenticated endpoints.
          For example, you can filter the list of available drinks by type.
        position: 2
      servers:
        - url: https://speakeasy.bar
        - url: https://test.speakeasy.bar
      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.
      x-speakeasy-usage-example:
        description: |-
          Specifying tags for this extension allows selecting the operation for specific README sections.
          If the "tags" array is not provided or if it contains the tag "usage", a usage snippet associated
          with the operation will be inserted in the main "SDK Example Usage" section. In this case a "title"
          and "description" can be provided for this example and its relative positioning can be set through
          the "position" attribute. "title", "description" and "position" have no effect for other tags.
        tags:
          - server  # Server Selection
          - security # Authentication
      tags:
        - ingredients
      parameters:
        - 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: array
                items:
                  $ref: "#/components/schemas/Ingredient"
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

  /order:
    post:
      operationId: createOrder
      summary: Create an order.
      description: Create an order for a drink.
      tags:
        - orders
      x-speakeasy-usage-example:
        title: "Create an order"
        description: |-
          When you submit an order, you can include a callback URL along your request.
          This URL will get called whenever the supplier updates the status of your order.
        position: 3
      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
      x-speakeasy-usage-example:
        title: "Subscribe to webhooks to receive stock updates"
        position: 3
        tags:
          - usage    # SDK Example Usage
          - retries  # Retries
          - errors   # Error Handling
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 10 # 10 ms
          maxInterval: 200 # 200 ms
          maxElapsedTime: 1000 # 1 seconds
          exponent: 1.5
        statusCodes:
          - 404
        retryConnectionErrors: false
      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.
        "400":
          $ref: "#/components/responses/BadRequest"
        "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
          x-speakeasy-error-message: true
        details:
          type: object
          additionalProperties: true
    BadRequest:
      type: object
      properties:
        status_code:
          type: number
          description: HTTP status code
          example: 400
        error:
          type: string
          description: Contains an explanation of the status_code as defined in HTTP/1.1 standard (RFC 7231)
          example: Bad Request
        type_name:
          type: string
          description: The type of error returned
          example: RequestValidationError
    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
      x-speakeasy-example: <YOUR_API_KEY>
    bearerAuth:
      type: http
      scheme: bearer
      x-speakeasy-example: <YOUR_JWT>
    basicHttp:
      type: http
      scheme: basic
      x-speakeasy-example: <USERNAME>;<PASSWORD>
  responses:
    APIError:
      description: An error occurred interacting with the API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BadRequest"
    UnknownError:
      description: An unknown error occurred interacting with the API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"