openapi.yml

openapi: 3.0.3
info:
  title: Fauna JavaScript sample app
  description: |
    HTTP API reference documentation for the [Fauna JavaScript sample
    app](https://github.com/fauna/js-sample-app).

    The app uses Fauna and Node.js to create HTTP API endpoints for a sample
    e-commerce store. You can use the endpoints to  manage customers,
    products, and orders for the store.

    For an overview and more details, see the
    [README](https://github.com/fauna/js-sample-app).

    ## Authentication

    Requests to the endpoints require no authentication. Internally, requests to
    Fauna are authenticated using a Fauna key's secret. You pass the secret
    using the `FAUNA_SECRET` environment variable in `.env`.

    For setup instructions, see the
    [README](https://github.com/fauna/js-sample-app).
servers:
  - url: /
    description: Local development server
tags:
  - name: Customers
    description: "Get, create, and update customers for the e-commerce store."
  - name: Products
    description: "Get, create, and update products for the e-commerce store."
  - name: Orders
    description: |
      Get, create, and update customer orders for the e-commerce store.

      You can also use these endpoints to create and udpate a customer's cart.
      A customer's cart is an order with the `cart` status. A customer can have
      one cart at a time.

      An order contains zero or more items. An item links a product, with a
      quantity, to an order.
components:
  schemas:
    CustomerRequest:
      type: object
      required:
        - name
        - email
        - address
      properties:
        name:
          type: string
          description: Customer name
        email:
          type: string
          format: email
          description: |
            Customer's email address. Must be unique.

            Internally, the `Customer` collection uses a unique constraint to
            ensure `email` values are unique across customers.
        address:
          type: object
          description: Customer's mailing address.
          required:
            - street
            - city
            - state
            - postalCode
            - country
          properties:
            street:
              type: string
              description: Street of the customer's mailing address.
            city:
              type: string
              description: City of the customer's mailing address.
            state:
              type: string
              description: State of the customer's mailing address.
            postalCode:
              type: string
              description: Postal code of the customer's mailing address.
            country:
              type: string
              description: Country of the customer's mailing address.
      example:
        name: John Doe
        email: john.doe@example.com
        address:
          street: 123 Main St
          city: San Francisco
          state: CA
          postalCode: "12345"
          country: United States
    CustomerResponse:
      type: object
      properties:
        id:
          type: string
          description: "Unique, auto-generated ID for the customer."
        name:
          type: string
          description: Customer name.
        email:
          type: string
          format: email
          description: Customer's email address. Must be unique.
        address:
          type: object
          description: Customer's mailing address.
          properties:
            street:
              type: string
              description: Street of the customer's mailing address.
            city:
              type: string
              description: City of the customer's mailing address.
            state:
              type: string
              description: State of the customer's mailing address.
            postalCode:
              type: string
              description: Postal code of the customer's mailing address.
            country:
              type: string
              description: Country of the customer's mailing address.
      example:
        id: "111"
        name: John Doe
        email: john.doe@example.com
        address:
          street: 123 Main St
          city: San Francisco
          state: CA
          postalCode: "12345"
          country: United States
    ProductRequest:
      type: object
      required:
        - name
        - description
        - price
        - stock
        - category
      properties:
        name:
          type: string
          description: |
            Name of the product. Must be unique.

            Internally, the `Product` collection uses a unique constraint to
            ensure `name` values are unique across products.
        description:
          type: string
          description: Description of the product.
        price:
          type: integer
          description: |
            Price of the product in USD cents.

            Internally, the `Product` collection uses a check constraint to
            ensure `price` is an integer greater than zero.
        stock:
          type: integer
          description: |
            Quantity of the product available in stock.

            Internally, the `Product` collection uses a check constraint to
            ensure `stock` is greater than or equal to zero.
        category:
          type: string
          description: >
            Name of the product's category. Must match an existing category.


            Internally, this field contains a reference to a `Category`
            collection

            document.
      example:
        name: The Old Man and the Sea
        price: 899
        description: A book by Ernest Hemingway
        stock: 10
        category: books
    ProductPageResponse:
      type: object
      properties:
        results:
          type: array
          description: Page of products.
          items:
            $ref: "#/components/schemas/ProductResponse"
        nextToken:
          type: string
          description: |
            Pagination token. Pass the token to the endpoint's `nextToken` query
            parameter to get the next page of results.
      example:
        results:
          - id: "123"
            name: The Old Man and the Sea
            price: 899
            description: A book by Ernest Hemingway
            stock: 10
            category:
              id: "123"
              name: books
              description: Bargain books!
        nextToken: hdW...
    ProductResponse:
      type: object
      properties:
        id:
          type: string
          description: "Unique, auto-generated ID for the product."
        name:
          type: string
          description: Name of the product.
        price:
          type: integer
          description: Price of the product in USD cents.
        description:
          type: string
          description: Description of the product.
        stock:
          type: integer
          description: Quantity of the product available in stock.
        category:
          type: object
          description: Category to which the product belongs.
          properties:
            id:
              type: string
              description: "Unique, auto-generated ID for the category."
            name:
              type: string
              description: Name of the category.
            description:
              type: string
              description: Description of the category.
      example:
        id: "123"
        name: The Old Man and the Sea
        price: 899
        description: A book by Ernest Hemingway
        stock: 10
        category:
          id: "123"
          name: books
          description: Bargain books!
    FilteredProductPageResponse:
      type: object
      properties:
        data:
          type: array
          description: Page of filtered products.
          items:
            $ref: "#/components/schemas/FilteredProductResponse"
        nextToken:
          type: string
          description: |
            Pagination token. Pass the token to the endpoint's `nextToken` query
            parameter to get the next page of results.
      example:
        results:
          - id: "123"
            name: The Old Man and the Sea
            description: A book by Ernest Hemingway
            price: 899
            stock: 10
            category:
              id: "123"
              name: "books"
              description: "Bargain books!"
        nextToken: hdW...
    FilteredProductResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the product.
        description:
          type: string
          description: Description of the product.
        price:
          type: integer
          description: Price of the product in USD cents.
        stock:
          type: integer
          description: Quantity of the product available in stock.
      example:
        name: The Old Man and the Sea
        description: A book by Ernest Hemingway
        price: 899
        stock: 10
    OrderRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - cart
            - processing
            - shipped
            - delivered
          description: |
            Status of the order.

            An order's status can only transition as follows:

            `cart` → `processing` → `shipped` → `delivered`

            Internally, the endpoint uses the `validateOrderStatusTransition()`
            user-defined function (UDF) to ensure an order's  `status` change is
            allowed.
        payment:
          type: object
          default: {}
          description: |
            Arbitrary object containing payment information.

            You can only update payment information if the `status` is `cart`.
            Adding payment information automatically transitions the order's
            `status` to `processing`.
      example:
        status: processing
    OrderPageResponse:
      type: object
      properties:
        results:
          type: array
          description: Page of orders.
          items:
            $ref: "#/components/schemas/OrderResponse"
        nextToken:
          type: string
          description: |
            Pagination token. Pass the token to the endpoint's `nextToken` query
            parameter to get the next page of results.
      example:
        results:
          - id: "123"
            payment: {}
            createdAt: "2099-08-09T16:43:07.153186Z"
            status: cart
            total: 899
            items:
              - product:
                  id: "123"
                  name: For Whom the Bell Tolls
                  price: 899
                  description: A book by Ernest Hemingway
                  stock: 10
                  category:
                    id: "123"
                    name: books
                    description: Bargain books!
                quantity: 1
            customer:
              id: "111"
              name: John Doe
              email: john.doe@example.com
              address:
                street: 123 Main St
                city: San Francisco
                state: CA
                postalCode: "12345"
                country: United States
        nextToken: hdW...
    OrderResponse:
      type: object
      properties:
        id:
          type: string
          description: "Unique, auto-generated ID for the order."
        payment:
          type: object
          description: Payment details for the order (currently empty).
        createdAt:
          type: string
          format: date-time
          description: ISO-8601-formatted timestamp of when the order was created.
        status:
          type: string
          description: Current status of the order.
          enum:
            - cart
            - processing
            - shipped
            - delivered
        total:
          type: integer
          description: Total cost of the order.
        items:
          type: array
          description: Items in the order.
          items:
            $ref: "#/components/schemas/OrderItem"
        customer:
          $ref: "#/components/schemas/CustomerResponse"
      example:
        id: "123"
        payment: {}
        createdAt: "2099-08-09T16:43:07.153186Z"
        status: cart
        total: 899
        items:
          - product:
              id: "123"
              name: For Whom the Bell Tolls
              price: 899
              description: A book by Ernest Hemingway
              stock: 10
              category:
                id: "123"
                name: books
                description: Bargain books!
            quantity: 1
        customer:
          id: "111"
          name: John Doe
          email: john.doe@example.com
          address:
            street: 123 Main St
            city: San Francisco
            state: CA
            postalCode: "12345"
            country: United States
    OrderItem:
      type: object
      properties:
        product:
          $ref: "#/components/schemas/ProductResponse"
        quantity:
          type: integer
          description: Quantity of the product in the order.
      example:
        product:
          id: "123"
          name: For Whom the Bell Tolls
          price: 899
          description: A book by Ernest Hemingway
          stock: 7
          category:
            id: "123"
            name: books
            description: Bargain books!
          quantity: 1
    OrderItemRequest:
      type: object
      required:
        - productName
        - quantity
      properties:
        productName:
          type: string
          description: |
            Name of an existing product to add to the order.
        quantity:
          type: integer
          description: >
            Quantity of the product to add to the order.

            Must be a non-negative integer. The quantity must be less than the
            product's `stock`.

            Internally, the `OrderItem` collection uses a check constraint to
            ensure `quantity` is a positive integer.
      example:
        productName: The Old Man and the Sea
        quantity: 1
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message.
      example:
        message: Invalid request parameter
paths:
  /customers:
    post:
      summary: Create a customer.
      operationId: create-customer
      security:
        - {}
      tags:
        - Customers
      description: Create a customer with the specified details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerRequest"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-name:
                  summary: Invalid name.
                  value:
                    message: Name must be a non-empty string.
                invalid-email:
                  summary: Invalid email.
                  value:
                    message: Email must be a non-empty string.
                invalid-address:
                  summary: Invalid address.
                  value:
                    message: >-
                      Address must contain a street, city, state, postalCode and
                      country represented as strings.
                invalid-request:
                  summary: Invalid customer request.
                  value:
                    message: >-
                      Unable to create customer, please check that the fields in
                      your request body are valid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized.
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Customer email already exists.
                  value:
                    message: A customer with that email already exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error.
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X POST http://localhost:8000/customers \
              --header 'content-type: application/json' \
              --data '{"name":"John Doe","email":"john.doe@example.com","address":{"street":"123 Main St","city":"San Francisco","state":"CA","postalCode":"12345","country":"United States"}}'
  "/customers/{id}":
    get:
      summary: Get a customer.
      operationId: get-customer
      security:
        - {}
      tags:
        - Customers
      description: Fetch the details of a customer by their ID.
      parameters:
        - name: id
          in: path
          description: ID of the customer to retrieve.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Invalid id
                  value:
                    message: Invalid id '!' provided.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v http://localhost:8000/customers/111
    patch:
      summary: Update a customer.
      operationId: update-customer
      security:
        - {}
      tags:
        - Customers
      description: Update the details of a customer by their ID.
      parameters:
        - name: id
          in: path
          description: ID of the customer to update.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-name:
                  summary: Invalid name.
                  value:
                    message: Name must be a non-empty string or be omitted.
                invalid-email:
                  summary: Invalid email.
                  value:
                    message: Name must be a non-empty string or be omitted.
                invalid-address:
                  summary: Invalid address.
                  value:
                    message: >-
                      Address must contain a street, city, state, postalCode and
                      country represented as strings or be omitted.
                invalid-request:
                  summary: Invalid customer request.
                  value:
                    message: >-
                      Unable to create customer, please check that the fields in
                      your request body are valid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Customer email already exists
                  value:
                    message: A customer with that email already exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X PATCH http://localhost:8000/customers/111 \
              --header 'content-type: application/json' \
              --data '{"name":"John Doe","email":"john.doe@example.com","address":{"street":"123 Main St","city":"San Francisco","state":"CA","postalCode":"12345","country":"United States"}}'
  /products:
    get:
      summary: Get a page of products.
      operationId: get-products
      security:
        - {}
      tags:
        - Products
      parameters:
        - name: category
          in: query
          schema:
            type: string
          description: Category name to filter products by.
        - name: nextToken
          in: query
          schema:
            type: string
          description: |
            Accepts a pagination token. The endpoint's responses
            return these tokens in the `nextToken` property.
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
          description: Number of products to return per page.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductPageResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-cat:
                  summary: Invalid category.
                  value:
                    message: Category must be a string or be omitted.
                cat-not-found:
                  summary: Category not found.
                  value:
                    message: Category does not exist.
                invalid-pagesize:
                  summary: Invalid pageSize.
                  value:
                    message: Page size must be a positive integer or be omitted.
                invalid-next-token:
                  summary: Invalid nextToken.
                  value:
                    message: Next token must be a string or be omitted.
                invalid-query:
                  summary: Invalid product request.
                  value:
                    message: >-
                      Unable to create product, please check that the fields in
                      your request body are valid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized.
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error.
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v 'http://localhost:8000/products?category=books&pageSize=1'
    post:
      summary: Create a product.
      operationId: create-product
      security:
        - {}
      tags:
        - Products
      description: Create a product with the specified details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductRequest"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-name:
                  summary: Invalid name.
                  value:
                    message: Name must be a non-empty string.
                invalid-price:
                  summary: Invalid price.
                  value:
                    message: Price must be an integer greater than 0.
                invalid-desc:
                  summary: Invalid description.
                  value:
                    message: Description must be a non-empty string.
                invalid-stock:
                  summary: Invalid stock.
                  value:
                    message: Stock must be an integer greater than or equal to 0.
                invalid-cat:
                  summary: Invalid category.
                  value:
                    message: Category must be a non-empty string.
                cat-not-found:
                  summary: Category not found.
                  value:
                    message: Category does not exist.
                invalid-query:
                  summary: Invalid product request.
                  value:
                    message: >-
                      Unable to create product, please check that the fields in
                      your request body are valid.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized.
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Customer email already exists.
                  value:
                    message: A product with that name already exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error.
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X POST http://localhost:8000/products \
              --header 'content-type: application/json' \
              --data '{"name":"The Old Man and the Sea","price":899,"description":"A book by Ernest Hemingway","stock":10,"category":"books"}'
  "/products/{id}":
    patch:
      summary: Update a product.
      operationId: update-product
      security:
        - {}
      tags:
        - Products
      description: Update the details of a product by its ID.
      parameters:
        - name: id
          in: path
          description: ID of the product to update.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-name:
                  summary: Invalid name.
                  value:
                    message: Name must be a non-empty string or be omitted.
                invalid-price:
                  summary: Invalid price.
                  value:
                    message: Price must be an integer greater than 0 or be omitted.
                invalid-desc:
                  summary: Invalid description.
                  value:
                    message: Description must be a string or be omitted.
                invalid-stock:
                  summary: Invalid stock.
                  value:
                    message: >-
                      Stock must be an integer greater than or equal to 0 or be
                      omitted.
                invalid-cat:
                  summary: Invalid category.
                  value:
                    message: Category must be a string or be omitted.
                cat-not-found:
                  summary: Category not found.
                  value:
                    message: Category does not exist.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized.
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No product with id
                  value:
                    message: No product with id '111' exists.
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Product name already exists.
                  value:
                    message: A product with that name already exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error.
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X PATCH http://localhost:8000/products/123 \
              --header 'content-type: application/json' \
              --data '{"name":"The Old Man and the Sea","price":899,"description":"A book by Ernest Hemingway","stock":10,"category":"books"}'
  /products/by-price:
    get:
      summary: Get a page of products by price.
      operationId: get-products-by-price
      security:
        - {}
      tags:
        - Products
      parameters:
        - name: minPrice
          in: query
          schema:
            type: integer
          description: Minimum price, in USD cents, to filter products by.
        - name: maxPrice
          in: query
          schema:
            type: integer
          description: Maximum price, in USD cents, to filter products by.
        - name: nextToken
          in: query
          schema:
            type: string
          description: |
            Accepts a pagination token. The endpoint's responses
            return these tokens in the `nextToken` property.
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 10
          description: Number of products to return per page.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FilteredProductPageResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized.
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error.
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v 'http://localhost:8000/products/by-price?minPrice=199&maxPrice=1099&pageSize=1'
  "/customers/{id}/cart":
    get:
      summary: Get a customer's cart.
      operationId: get-customer-cart
      security:
        - {}
      tags:
        - Orders
      description: |
        Get the details of a customer's cart order.
      parameters:
        - description: ID of the customer.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v http://localhost:8000/customers/111/cart
    post:
      summary: Get or create a customer's cart.
      operationId: get-create-customer-cart
      security:
        - {}
      tags:
        - Orders
      description: |
        Get the details of a customer's cart. If no cart exists, create one with
        no items.

        A customer's cart is an order with the `cart` status. A customer can
        have one cart at a time.

        To add items to a customer's cart, use the `POST
        /customers/{id}/cart/item` endpoint.

        Internally, the endpoint uses the `getOrCreateCart()` user-defined
        function (UDF) to conditionally get or create the customer's cart.
      parameters:
        - description: ID of the customer.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X POST http://localhost:8000/customers/111/cart
  "/customers/{id}/cart/item":
    post:
      summary: Add an item to a customer's cart.
      operationId: add-cart-item
      security:
        - {}
      tags:
        - Orders
      description: |
        Add an item to a customer's cart. If the order already contains the
        item's product, update the item's quantity.

        If the customer has no cart, the request create ones.

        The request returns an item. An item links a product, with a quantity,
        to an order. An order contains zero or more items.

        Internally, the endpoint uses the `createOrUpdateCartItem()`
        user-defined function (UDF) to conditionally update the item's quantity
        and create a new cart. The UDF also handles various validations and
        error cases for the request.
      parameters:
        - description: ID of the customer.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderItemRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-product:
                  summary: Invalid product.
                  value:
                    message: Product must be a non empty string.
                invalid-quantity:
                  summary: Invalid quantity.
                  value:
                    message: Quantity must be a positive integer.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X POST http://localhost:8000/customers/111/cart/item \
              --header 'content-type: application/json' \
              --data '{"productName":"The Old Man and the Sea","quantity":1}'
  "/orders/{id}":
    get:
      summary: Get an order.
      operationId: get-order
      security:
        - {}
      tags:
        - Orders
      description: Get the details of an order by its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: ID of the order to fetch.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Invalid id
                  value:
                    message: Invalid id '!' provided.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No order with id
                  value:
                    message: No order with id '111' exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v http://localhost:8000/orders/123
    patch:
      summary: Update an order.
      operationId: update-order
      security:
        - {}
      tags:
        - Orders
      description: >
        Update the details of an order by its ID.


        Changing the order's `status` to `processing` runs a checkout on the
        order.


        Internally, the endpoint uses the `checkout()` user-defined function

        (UDF) to validate orders during checkout. The UDF:

         * Verifies the order is in a `processing` status.
         * Ensures the order only adds valid, existing products as items.
         * Verifies that the order does not reduce any product's stock below zero.
         * Ensures the order has a non-null `payment`.
      parameters:
        - name: id
          in: path
          description: ID of the order to update.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-payment-change-a:
                  summary: Payment change not allowed.
                  value:
                    message: >-
                      Payment method may only be updated before the order has
                      been placed.
                invalid-payment-change-b:
                  summary: Payment change not allowed.
                  value:
                    message: >-
                      Can not update payment information after an order has been
                      placed.
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: Unauthorized
                  value:
                    message: >-
                      Unauthorized. Set the `FAUNA_SECRET` env var to a valid
                      Fauna key's secret.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No order with id
                  value:
                    message: No order with id '111' exists.
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example-1:
                  summary: Internal server error
                  value:
                    message: An unexpected error occurred
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v -X PATCH http://localhost:8000/orders/123 \
              --header 'content-type: application/json' \
              --data '{"status":"processing"}'
  "/customers/{id}/orders":
    get:
      summary: Get a customer's orders.
      operationId: get-customer-order
      security:
        - {}
      tags:
        - Orders
      description: Get the details of a customer's orders using the customer's ID.
      parameters:
        - description: ID of the customer.
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: |
            Accepts a pagination token. The endpoint's responses
            return these tokens in the `nextToken` property.
          in: query
          name: nextToken
          schema:
            type: string
        - description: Number of products to return per page.
          in: query
          name: pageSize
          schema:
            default: 10
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderPageResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalid-pagesize:
                  summary: Invalid pageSize.
                  value:
                    message: Page size must be a positive integer or be omitted.
                invalid-next-token:
                  summary: Invalid nextToken.
                  value:
                    message: Next token must be a string or be omitted.
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                example:
                  summary: No customer with id
                  value:
                    message: No customer with id '111' exists.
      x-codeSamples:
        - lang: curl
          source: |-
            curl -v 'http://localhost:8000/customers/111/orders?pageSize=1'