openapi: 3.0.3
info:
  version: 1.0.0
  title: Product Add-ons
  x-logo:
    url: https://www.ikea.com/ph/en/static/ikea-logo.f7d9229f806b59ec64cb.svg
  description: >
    ## What is it?


    The Product Add-ons API provides a list of products to recommend, with basic product information

    and additional relevant attributes, from IKEA Knowledge Graph

    ## How to get access?


    To request access to the API and Documentation about it's design send an email to [ikea.knowledge.graph@inter.ikea.com](mailto:ikea.knowledge.graph@inter.ikea.com) with any questions


    We also accept requests for new features


    <hr />

  contact:
    email: ikea.knowledge.graph@inter.ikea.com
servers:
  - url: https://knowledge-dev.api.inter.ikea.net/cbr/rosd/ikg/dev/api/product-add-ons/v1
    description: Development environment
    x-environment: dev
  - url: https://knowledge-stage.api.inter.ikea.net/cbr/rosd/ikg/test/api/product-add-ons/v1
    description: Staging environment
    x-environment: stage
  - url: https://knowledge.api.inter.ikea.net/cbr/rosd/ikg/api/product-add-ons/v1
    description: Production environment
    x-environment: prod
tags:
  - name: Add-ons
    description: API endpoints that return add-on products for a specific product(s), provided in the query
security:
  - SubscriptionKey: []
paths:
  /products/add-ons:
    get:
      tags:
        - Add-ons
      summary: Get a list of product item(article) numbers, passed in the query, with their add-ons
      description: >
        This endpoint takes a comma (,) separated list of product item(article) numbers that are passed in the query and returns a list of product item(article) numbers, passed in the query, with their add-ons. The add-ons contain information on their relation to the input product, sorted by relevancy. If the products do not have any add-on products then it returns an empty array

      operationId: getAddonsByProductsIds
      parameters:
        - in: query
          name: products
          description: A comma (`,`) separated list of product item(article) numbers
          schema:
            type: array
            items:
              minLength: 8
              maxLength: 8
              type: string
            minItems: 1
            maxItems: 50
            uniqueItems: true
          style: form
          explode: false
          required: true
        - in: query
          name: retailUnits
          description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter.
          schema:
            type: array
            items:
              type: string
            uniqueItems: true
          style: form
          explode: false
          required: false
        - in: query
          name: limitPerMainProductType
          description: Maximum number of items to return per main product type
          schema:
            type: integer
          example: 10
        - in: query
          name: enableMarketSalesDate
          description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date.
          schema:
            type: boolean
      responses:
        "200":
          description: >-
            Returns a list of ProductWithAddons objects or an empty array, if no add-on products are found in the IKEA Knowledge graph.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProductWithAddons"
              examples:
                ProductWithAddons:
                  value:
                    - itemNo: "15456789"
                      productAddons:
                        - itemType: ART
                          itemNo: "23456789"
                          itemName: "Product item Name"
                          retailUnits:
                            - se
                            - nl
                          mainProductType:
                            number: "12010"
                            name: "blankets"
                          relevanceScore: 100
                          relations:
                            - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsComfort"
                              name: "adds comfort"
                        - itemType: ART
                          itemNo: "12345679"
                          itemName: "Product item Name"
                          retailUnits:
                            - se
                          mainProductType:
                            number: "12030"
                            name: "cleaning tools"
                          relevanceScore: 110
                          relations:
                            - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsComfort"
                              name: "adds comfort"
                            - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsCareAndMaintenance"
                              name: "adds care and maintenance"
                    - itemNo: "17198402"
                      productAddons:
                        - itemType: ART
                          itemNo: "30285012"
                          itemName: "Product item Name"
                          retailUnits:
                            - nl
                          mainProductType:
                            number: "12030"
                            name: "cleaning tools"
                          relevanceScore: 101
                          relations:
                            - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsCareAndMaintenance"
                              name: "adds care and maintenance"
                        - itemType: ART
                          itemNo: "29174103"
                          itemName: "Product item Name"
                          retailUnits:
                            - se
                            - nl
                          mainProductType:
                            number: "12010"
                            name: "blankets"
                          relevanceScore: 111
                          relations:
                            - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsCareAndMaintenance"
                              name: "adds care and maintenance"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /products/{itemNo}/add-ons:
    get:
      tags:
        - Add-ons
      summary: Get a list of add-on products by item(article) number
      description: This endpoint takes a product item(article) number and returns a list of add-on products, with information on their relation to the input product, ordered by relevancy. If the product does not have any add-on products it returns an empty array
      operationId: getAddonsByProductId
      parameters:
        - in: path
          name: itemNo
          description: The 8-digit item number, also known as the article number, of a product
          schema:
            type: string
            pattern: '^\d+$'
            minLength: 8
            maxLength: 8
          example: "12345678"
          required: true
        - in: query
          name: retailUnits
          description: A comma (`,`) separated list of retail units. If no retail units are provided, the retail unit associated with the queried product is used as the filter. If retail units are provided, the resulting output is filtered by the common retail units between the product's retail units and those passed via the retail units query parameter.
          schema:
            type: array
            items:
              type: string
            uniqueItems: true
          style: form
          explode: false
          required: false
        - in: query
          name: limitPerMainProductType
          description: Maximum number of items to return per main product type
          schema:
            type: integer
          example: 10
        - in: query
          name: enableMarketSalesDate
          description: Include products covering a range of 56 days before the sale start date to 360 days after the sale end date.
          schema:
            type: boolean
      responses:
        "200":
          description: >-
            Returns a list of ProductAddon objects, sorted by relevanceScore, or an empty array, if no add-on products are defined in the IKEA knowledge graph
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProductAddon"
              examples:
                productAddons:
                  value:
                    - itemType: ART
                      itemNo: "23456789"
                      itemName: "Product item Name"
                      retailUnits:
                        - es
                        - au
                      mainProductType:
                        number: "12010"
                        name: "blankets"
                      relevanceScore: 100
                      relations:
                        - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsComfort"
                          name: "adds comfort"
                    - itemType: ART
                      itemNo: "12345679"
                      itemName: "Product item Name"
                      retailUnits:
                        - es
                        - au
                      mainProductType:
                        number: "12010"
                        name: "cleaning tools"
                      relevanceScore: 110
                      relations:
                        - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsCareAndMaintenance"
                          name: "adds care and maintenance"
                    - itemType: ART
                      itemNo: "12345789"
                      itemName: "Product item Name"
                      retailUnits:
                        - es
                      mainProductType:
                        number: "12010"
                        name: "cleaning tools"
                      relevanceScore: 101
                      relations:
                        - iri: "https://knowledge.ikea.net/home-furnishing-ontology/addsCareAndMaintenance"
                          name: "adds care and maintenance"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    ProductWithAddons:
      title: ProductWithAddons
      description: Contains a product identifier and a list of products considered to be add-ons for it.
      properties:
        itemNo:
          description: The IKEA Product item number, also known as article number
          type: string
          pattern: '^\d+$'
          minLength: 8
          maxLength: 8
        productAddons:
          type: array
          items:
            $ref: "#/components/schemas/ProductAddon"
    ProductAddon:
      title: ProductAddon
      description: A product considered to be an add-on to the queried product. Contains information about the product, why it's considered an addon, and its relevance as a recommendation
      properties:
        itemType:
          description: An IKEA Product type (e.g `ART` or `SPR`)
          type: string
          enum:
            - ART
            - SPR
        itemNo:
          description: The IKEA Product item number, also known as article number
          type: string
          pattern: '^\d+$'
          minLength: 8
          maxLength: 8
        itemName:
          description: The IKEA Product item name
          type: string
        retailUnits:
          description: A list of retail units. A compilation of retail units is available at http://knowledge.ikea.net/retail-system-module/retail-units-taxonomy
          type: array
          items:
            type: string
            description: A retail unit identifier
        mainProductType:
          $ref: "#/components/schemas/MainProductType"
        relevanceScore:
          description: A number, indicating the add-on relevancy order to the queried product. A lower value indicates higher relevancy
          type: number
        relations:
          description: A list of relations between the add-on product and the queried product
          type: array
          items:
            $ref: "#/components/schemas/Relation"
      required:
        - itemType
        - itemNo
        - itemName
        - retailUnits
        - mainProductType
        - relevanceScore
        - relations
    Relation:
      title: Relation
      description: An add-on relation between the add-on product and the queried product
      properties:
        iri:
          type: string
          description: The IKEA Knowledge Graph identifier
        name:
          type: string
          description: The name of the relation the add-on product has to the queried product
    MainProductType:
      title: MainProductType
      description: The collection represents the member product types. The product type describes the function of a product from a customer's perspective.
      properties:
        number:
          type: string
          description: A five digit unique identifier as a string
        name:
          type: string
          description: The collection name that represents the member product types
    Error:
      title: Error
      description: A generic error response
      properties:
        status:
          type: number
        type:
          type: string
        message:
          type: string
      required:
        - status
        - type
        - message
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerError:
      description: A request to the server cannot be processed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    SubscriptionKey:
      type: apiKey
      name: Subscription-Key
      in: header