shop.json

swagger: '2.0'
host: 'api.predic8.de:443'
basePath: /shop
schemes:
  - https
info:
  title: Fruit Shop API
  version: 1.0.0
  description: >-
    This is a showcase for REST API design and serves as a public API for
    educational usage.
  contact:
    name: Thomas Bayer
    url: 'http://predic8.de'
    email: bayer@predic8.de
tags:
  - name: categories
  - name: customers
  - name: orders
  - name: products
  - name: vendors
paths:
  /categories/:
    get:
      summary: Lists all the product categories
      operationId: getShopCategories
      tags:
        - categories
      responses:
        '200':
          description: List of categories
          schema:
            $ref: '#/definitions/CategoryList'
  '/categories/{id}':
    get:
      summary: Get a category by id
      operationId: getShopCategoriesId
      parameters:
        - type: string
          description: Id of a category
          name: id
          in: path
          required: true
      tags:
        - categories
      responses:
        '200':
          description: Collection of products
          schema:
            $ref: '#/definitions/ProductList'
  '/customers/{id}':
    get:
      summary: Get a customer by id
      operationId: getShopCustomersId
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
      tags:
        - customers
      responses:
        '200':
          description: Customer details
          schema:
            $ref: '#/definitions/Customer'
    put:
      summary: Replace a customer by new data
      operationId: putShopCustomersId
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Customer'
      tags:
        - customers
      responses:
        '200':
          description: Customer details
          schema:
            $ref: '#/definitions/Customer'
    patch:
      summary: Update a customer
      operationId: patchShopCustomersId
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/CustomerPatch'
      tags:
        - customers
      responses:
        '200':
          description: Customer details
          schema:
            $ref: '#/definitions/Customer'
    delete:
      summary: Delete a customer
      operationId: deleteShopCustomersId
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
      tags:
        - customers
      responses:
        default:
          schema:
            type: string
          description: Successful
  /customers/:
    get:
      summary: Lists all the customers
      operationId: getShopCustomers
      tags:
        - customers
      responses:
        '200':
          description: Collection of customers
          schema:
            $ref: '#/definitions/CustomerList'
    post:
      summary: Create a customer
      operationId: postShopCustomers
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Customer'
      tags:
        - customers
      responses:
        '200':
          description: Customer details
          schema:
            $ref: '#/definitions/Customer'
  '/orders/{id}':
    get:
      summary: Get an order by id
      operationId: getShopOrdersId
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
      tags:
        - orders
      responses:
        '200':
          description: Order details
          schema:
            $ref: '#/definitions/Order'
    delete:
      summary: Delete an order
      operationId: deleteShopOrdersId
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
      tags:
        - orders
      responses:
        default:
          schema:
            type: string
          description: Successful
  /orders/:
    get:
      summary: Lists all the orders
      operationId: getShopOrders
      parameters:
        - type: string
          description: State of the order
          enum:
            - created
            - ordered
            - delivered
            - canceled
          name: state
          in: query
      tags:
        - orders
      responses:
        '200':
          description: Collection of orders
          schema:
            $ref: '#/definitions/OrderList'
  '/products/{id}':
    get:
      summary: Get a product by id
      operationId: getShopProductsId
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
      tags:
        - products
      responses:
        '200':
          description: Product description
          schema:
            $ref: '#/definitions/Product'
    put:
      summary: Replace a product by new data
      operationId: putShopProductsId
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Product'
      tags:
        - products
      responses:
        '200':
          description: Product description
          schema:
            $ref: '#/definitions/Product'
    patch:
      summary: Update one or more properties of a product
      operationId: patchShopProductsId
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/ProductPatch'
      tags:
        - products
      responses:
        '200':
          description: Product description
          schema:
            $ref: '#/definitions/Product'
    delete:
      summary: Delete a product
      operationId: deleteShopProductsId
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
      tags:
        - products
      responses:
        default:
          schema:
            type: string
          description: Successful
  /products/:
    get:
      summary: Lists all the products
      operationId: getShopProducts
      tags:
        - products
      responses:
        '200':
          description: Collection of products
          schema:
            $ref: '#/definitions/ProductList'
    post:
      summary: Create a product
      operationId: postShopProducts
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Product'
      tags:
        - products
      responses:
        default:
          schema:
            type: string
          description: Successful
  '/vendors/{id}':
    get:
      summary: Get a vendor by id
      operationId: getShopVendorsId
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
      tags:
        - vendors
      responses:
        '200':
          description: Vendor of products
          schema:
            $ref: '#/definitions/Vendor'
    put:
      summary: Replace a vendor by new data
      operationId: putShopVendorsId
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
      tags:
        - vendors
      responses:
        default:
          schema:
            type: string
          description: Successful
    patch:
      summary: Update a vendor
      operationId: patchShopVendorsId
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
      tags:
        - vendors
      responses:
        default:
          schema:
            type: string
          description: Successful
    delete:
      summary: Delete a vendor
      operationId: deleteShopVendorsId
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
      tags:
        - vendors
      responses:
        default:
          schema:
            type: string
          description: Successful
  /vendors/:
    get:
      summary: Lists all the vendors
      operationId: getShopVendors
      tags:
        - vendors
      responses:
        '200':
          description: Collection of vendors
          schema:
            $ref: '#/definitions/VendorList'
    post:
      summary: Create a vendor
      operationId: postShopVendors
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Vendor'
      tags:
        - vendors
      responses:
        '200':
          description: Vendor of products
          schema:
            $ref: '#/definitions/Vendor'
  '/products/{id}/photo':
    get:
      summary: Get a photo of a product
      operationId: getShopProductsIdPhoto
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
      tags:
        - products
      responses:
        default:
          schema:
            type: string
          description: Successful
    put:
      summary: Add or update the photo of a product
      operationId: putShopProductsIdPhoto
      description: Length of the image is limited to 512 KBytes.
      parameters:
        - type: integer
          description: Id of a product
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/ProductImage'
      consumes:
        - multipart/form-data
      tags:
        - products
      responses:
        '200':
          description: Product description
          schema:
            $ref: '#/definitions/Product'
  '/customers/{id}/orders/':
    get:
      summary: Get the orders of a customer
      operationId: getShopCustomersIdOrders
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
      tags:
        - customers
      responses:
        '200':
          description: Collection of orders
          schema:
            $ref: '#/definitions/OrderList'
    post:
      summary: Create an order for a customer
      operationId: postShopCustomersIdOrders
      parameters:
        - type: integer
          description: Id of a customer
          name: id
          in: path
          required: true
      tags:
        - customers
      responses:
        '200':
          description: Order details
          schema:
            $ref: '#/definitions/Order'
  '/orders/{id}/items/':
    get:
      summary: Get the items of an order
      operationId: getShopOrdersIdItems
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
      tags:
        - orders
      responses:
        '200':
          description: Collection of items
          schema:
            $ref: '#/definitions/Items'
    post:
      summary: Add an item to an order
      operationId: postShopOrdersIdItems
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Item'
      tags:
        - orders
      responses:
        '200':
          description: Item details
          schema:
            $ref: '#/definitions/Item'
  '/orders/{oid}/items/{iid}':
    get:
      summary: Get an item of an order
      operationId: getShopOrdersOidItemsIid
      parameters:
        - type: integer
          description: Id of an order
          name: oid
          in: path
          required: true
        - type: integer
          description: Id of an item
          name: iid
          in: path
          required: true
      tags:
        - orders
      responses:
        '200':
          description: Item details
          schema:
            $ref: '#/definitions/Item'
    delete:
      summary: Delete an item of an order
      operationId: deleteShopOrdersOidItemsIid
      parameters:
        - type: integer
          description: Id of an order
          name: oid
          in: path
          required: true
        - type: integer
          description: Id of an item
          name: iid
          in: path
          required: true
      tags:
        - orders
      responses:
        default:
          schema:
            type: string
          description: Successful
  '/vendors/{id}/products/':
    get:
      summary: Get the products of a vendor
      operationId: getShopVendorsIdProducts
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
      tags:
        - vendors
      responses:
        default:
          schema:
            type: string
          description: Successful
    post:
      summary: Add a product to a vendor
      operationId: postShopVendorsIdProducts
      parameters:
        - type: integer
          description: Id of a vendor
          name: id
          in: path
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/NamePriceCategory'
      tags:
        - vendors
      responses:
        default:
          schema:
            type: string
          description: Successful
  '/orders/{id}/actions/purchase':
    post:
      summary: Purchase an order
      operationId: postShopOrdersIdActionsPurchase
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
      tags:
        - orders
      responses:
        default:
          schema:
            type: string
          description: Successful
  '/orders/{id}/actions/cancel':
    post:
      summary: Cancel an order
      operationId: postShopOrdersIdActionsCancel
      parameters:
        - type: integer
          description: Id of an order
          name: id
          in: path
          required: true
      tags:
        - orders
      responses:
        default:
          schema:
            type: string
          description: Successful
definitions:
  CategoryEntry:
    type: object
    description: Category entry
    x-meta:
      className: CategoryEntry
    properties:
      name:
        type: string
        description: Name of the category
        example: Fruits
      category_url:
        type: string
        example: /shop/categories/Fruits
    required:
      - name
  categories:
    type: array
    items:
      $ref: '#/definitions/CategoryEntry'
  CategoryList:
    type: object
    description: List of categories
    x-meta:
      className: CategoryList
    properties:
      categories:
        $ref: '#/definitions/categories'
  Meta:
    type: object
    description: Metadata about a collection of resources.
    x-meta:
      className: Meta
    properties:
      count:
        type: integer
        description: Total number of entries
        example: 22
      limit:
        type: integer
        description: How many entries are delivered in one response
        example: 10
      page:
        type: integer
        description: Number of the page within the results
        example: 2
      previous_url:
        type: string
        description: URL to the previous page of results
        example: /shop/products/?page=1&limit=10
      next_url:
        type: string
        description: URL to the next page of results
        example: /shop/products/?page=3&limit=10
    required:
      - count
  ProductEntry:
    type: object
    description: Entry of a product collection
    example:
      name: Pineapples
      product_url: /shop/products/33
    x-meta:
      className: ProductEntry
    properties:
      name:
        type: string
        description: Name of the product
      product_url:
        type: string
    required:
      - name
  products:
    type: array
    items:
      $ref: '#/definitions/ProductEntry'
  ProductList:
    type: object
    description: Collection of products
    x-meta:
      className: ProductList
    properties:
      meta:
        $ref: '#/definitions/Meta'
      products:
        $ref: '#/definitions/products'
  Customer:
    type: object
    description: Customer details
    example:
      firstname: Freddy
      lastname: Meyers
    x-meta:
      className: Customer
    properties:
      firstname:
        type: string
        example: Fred
      lastname:
        type: string
        example: Meyers
      orders_url:
        type: string
        description: Link to the orders of the customer
      customer_url:
        type: string
        description: Link to the customer resource
    required:
      - firstname
      - lastname
  CustomerEntry:
    type: object
    description: Entry of a collection of customers
    x-meta:
      className: customerEntry
    properties:
      firstname:
        type: string
        example: Susan
      lastname:
        type: string
        example: Tanner
      customer_url:
        type: string
        example: /shop/customer/642
    required:
      - firstname
      - lastname
  customers:
    type: array
    items:
      $ref: '#/definitions/CustomerEntry'
  CustomerList:
    type: object
    description: Collection of customers
    x-meta:
      className: CustomerList
    properties:
      meta:
        $ref: '#/definitions/Meta'
      customers:
        $ref: '#/definitions/customers'
  ActionDescription:
    type: object
    description: Description of a possible action on the resource
    x-meta:
      className: ActionDescription
    properties:
      url:
        type: string
        example: /shop/orders/7959/actions/purchase
      method:
        type: string
        enum:
          - POST
  Actions:
    type: object
    description: Actions that the order supports
    example:
      purchase:
        url: /shop/orders/7959/actions/purchase
        method: POST
    x-meta:
      className: Actions
    properties:
      purchase:
        $ref: '#/definitions/ActionDescription'
      cancel:
        $ref: '#/definitions/ActionDescription'
  Order:
    type: object
    description: Order details
    x-meta:
      className: Order
    properties:
      createdAt:
        type: string
        format: date
      updatedAt:
        type: string
        format: date
      state:
        type: string
        description: State of the order
        enum:
          - created
          - ordered
          - delivered
          - canceled
      customer_url:
        type: string
        example: /shop/customers/342
      actions:
        $ref: '#/definitions/Actions'
      items_url:
        type: string
      total:
        type: number
        description: Price of a good
        example: '4.50'
        x-constraint:
          positive: true
    required:
      - actions
  OrderEntry:
    type: object
    description: List entry of an order
    x-meta:
      className: OrderEntry
    properties:
      createdAt:
        type: string
        format: date
      state:
        type: string
        description: State of the order
        enum:
          - created
          - ordered
          - delivered
          - canceled
      order_url:
        type: string
        example: /shop/orders/7832
  orders:
    type: array
    items:
      $ref: '#/definitions/OrderEntry'
  OrderList:
    type: object
    description: Collection of orders
    x-meta:
      className: OrderList
    properties:
      meta:
        $ref: '#/definitions/Meta'
      orders:
        $ref: '#/definitions/orders'
  Product:
    type: object
    description: Product description
    example:
      name: Wildberries
      price: 4.99
      category_url: /shop/categories/Fruits
      vendor_url: /shop/vendors/672
    x-meta:
      className: Product
    properties:
      name:
        type: string
        description: Name of a product
        example: Berries
      price:
        type: number
        description: Price of a good
        example: '4.50'
        x-constraint:
          positive: true
      category:
        type: string
        description: Category of products e.g. Fruits
        example: Fruits
      vendor_url:
        type: string
      category_url:
        type: string
      vendor:
        type: integer
      photo_url:
        type: string
    required:
      - price
  Vendor:
    type: object
    description: Vendor of products
    example:
      name: Franks Fresh Fruits from France Ltd.
    x-meta:
      className: Vendor
    properties:
      name:
        type: string
        description: Name of the vendor
        example: foo
      products_url:
        type: string
        description: URL to the products of this vendor
      vendor_url:
        type: string
        description: URL of the vendor
    required:
      - name
  VendorEntry:
    type: object
    description: Listentry of a vendor
    x-meta:
      className: VendorEntry
    properties:
      name:
        type: string
        description: Name of the vendor
      vendor_url:
        type: string
    required:
      - name
  vendors:
    type: array
    items:
      $ref: '#/definitions/VendorEntry'
  VendorList:
    type: object
    description: Collection of vendors
    x-meta:
      className: VendorList
    properties:
      meta:
        $ref: '#/definitions/Meta'
      vendors:
        $ref: '#/definitions/vendors'
  Item:
    type: object
    description: Item details
    example:
      quantity: 5
      price: 0.9
      item_url: /shop/orders/1432/items/1
      product_url: /shop/products/3
    x-meta:
      className: Item
    properties:
      quantity:
        type: number
        example: 5
      price:
        type: number
        description: Price of a good
        example: '4.50'
        x-constraint:
          positive: true
      item_url:
        type: string
      product:
        type: number
      product_url:
        type: string
      order_url:
        type: string
    required:
      - price
  ItemList:
    type: array
    description: Collection of items
    x-meta:
      className: ItemList
    items:
      $ref: '#/definitions/Item'
  Items:
    type: object
    description: Collection of items
    x-meta:
      className: Items
    properties:
      order_url:
        type: string
        example: /shop/orders/1432
      items:
        $ref: '#/definitions/ItemList'
    required:
      - items
  File:
    type: object
  ProductImage:
    type: object
    description: Image of a product
    properties:
      file:
        $ref: '#/definitions/File'
  CustomerPatch:
    type: object
    description: 'Any properties of the customer can be updated e.g. { "firstname": "Kai" }'
    example:
      firstname: Fred
      lastname: Meyers
    x-meta:
      className: CustomerPatch
    properties:
      firstname:
        type: string
        example: Fred
      lastname:
        type: string
        example: Meyers
  ProductPatch:
    type: object
    description: Structure to patch a product. All the properties are optional.
    example:
      name: Wildberries
      price: 4.99
      category_url: /shop/categories/Fruits
      vendor_url: /shop/vendors/672
    x-meta:
      className: ProductPatch
    properties:
      name:
        type: string
        description: Name of a product
        example: Berries
      price:
        type: number
        description: Price of a good
        example: '4.50'
        x-constraint:
          positive: true
      category:
        type: string
        description: Category of products e.g. Fruits
        example: Fruits
      vendor_url:
        type: string
      category_url:
        type: string
      vendor:
        type: integer
  NamePriceCategory:
    type: object
    properties:
      name:
        type: string
      price:
        type: number
      category:
        type: string
    required:
      - name