openapi: "3.0.0"


################################################################################
# General Information
# SYSTEM_15: Recycle/Reuse Module integration
info:
  description: The ICT Platform Web Service for the 3.1 Recycle Module integration via a RESTful API.
  version: 1.0.2
  title: ICT Platform Recycle Module Web Service
  contact:
    name: Miltiadis Koutsokeras
    email: miltos.koutsokeras@iccs.gr
    url: https://www.iccs.gr/

# Deployed server endpoints
servers:
  - url: https://circ4life.iccs.gr/RecycleModule
    description: CIRC4Life ICT platform.
  - url: http://127.0.0.1:8083/RecycleModule
    description: Local debugging standalone server.
################################################################################


################################################################################
# Components
components:
  schemas:
    PurchaseHistory:
      description: Consumer's product list of past purchases
      type: array
      items:
        $ref: "CommonOpenAPI.yaml#/components/schemas/Product"

    EcoCreditsEstimationItem:
      type: object
      required:
        - eolstate
        - ecocredits
      properties:
        eolstate:
          $ref: "CommonOpenAPI.yaml#/components/schemas/EndOfLifeState"
        ecocredits:
          $ref: "CommonOpenAPI.yaml#/components/schemas/EcoCredits"

    EcoCreditsEstimation:
      description: Eco-credits estimation based on the product End of Life State
      type: array
      items:
        $ref: "#/components/schemas/EcoCreditsEstimationItem"

    RecycleEvaluationReport:
      description: Encapsulates the recycling company evaluator's report.
      type: object
      required:
        - consumer
        - report
      properties:
        consumer:
          $ref: "CommonOpenAPI.yaml#/components/schemas/RecycleBinUserID"
        report:
          description: Recycle evaluation report of a recycled item.
          type: object
          required:
            - recycledate
            - item
          properties:
            recycledate:
              $ref: "CommonOpenAPI.yaml#/components/schemas/Date"
            lifetime:
              description: The calculated or estimated lifetime of this recycled WEEEs item. Not present in Bio-waste items.
              type: object
              required:
                - years
                - extramonths
              properties:
                years:
                  $ref: "CommonOpenAPI.yaml#/components/schemas/yearsofuse"
                extramonths:
                  $ref: "CommonOpenAPI.yaml#/components/schemas/monthsofuse"
            item:
              type: object
              required:
                - wastetype
              properties:
                wastetype:
                  $ref: "CommonOpenAPI.yaml#/components/schemas/HSkey"
                product:
                  $ref: "CommonOpenAPI.yaml#/components/schemas/Product"
                weight:
                  description: Mass in grams (g) of the item in case of Bio-waste. Does not apply to WEEEs.
                  type: number
                  format: double
                  minimum: 0.0
            state:
              $ref: "CommonOpenAPI.yaml#/components/schemas/EndOfLifeState"
################################################################################


################################################################################
# Resource path URI endpoints
paths:
  #-----------------------------------------------------------------------------
  # 1. Endpoints for retrieving user's purchase history
  # USER_U_03, USER_U_04, USER_G_03: Get user's purchase history, optionally
  # filtered with specified product type parameter.
  # Results can be returned in a specific language by using the Query parameter
  # 'locale' and set its value equal to the ISO 639 alpha-2 language code, e.g.
  # for Spanish: /purchase_history/12345678901?locale=es

  # In this endpoint the whole 11 digits of the Consumer ID is used as an
  # identifier.
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /purchase_history/{consumerid}:
    get:
      description: USER_U_03 USER_U_04 USER_G_03 Get user's purchase history filtered with specified product type parameter.
      operationId: PurchaseHistoryGET
      parameters:
        - in: path
          name: consumerid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/RecycleBinUserID"
        - in: query
          name: locale
          required: false
          schema:
            description: ISO 639 alpha-2 language code for this locale
            type: string
            default: "en"
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: The user's purchase history.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PurchaseHistory"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Get the purchase history of a consumer, filtered to return only items of a
  # specific product type.
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /purchase_history/{consumerid}/type/{hskey}:
    get:
      description: USER_U_03 USER_U_04 USER_G_03 Get user's purchase history filtered with specified product type parameter.
      operationId: PurchaseHistoryByTypeGET
      parameters:
        - in: path
          name: consumerid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/RecycleBinUserID"
        - in: path
          name: hskey
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/HSkey"
        - in: query
          name: locale
          required: false
          schema:
            description: ISO 639 alpha-2 language code for this locale
            type: string
            default: "en"
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: The user's purchase history.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PurchaseHistory"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  #-----------------------------------------------------------------------------
  # 2. Endpoint for posting the recycle evaluation result
  # USER_R_02: Post Consumer and Product ID with recycler evaluation result
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /recycle_evaluation:
    post:
      description: USER_R_02 Post Consumer and Product ID with recycle evaluation result
      operationId: RecycleEvaluationPOST
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecycleEvaluationReport"
      responses:
        '200':
          description: Successful POST of data.
        '400':
          description: Malformed recycle evaluation form, client has sent a malformed recycle evaluation form
          content:
            '*/*':
              schema:
                type: string
        '404':
          description: The recycle bin user ID is not mapped to any Eco-account, no user record found for this user ID
          content:
            '*/*':
              schema:
                type: string
        '500':
          description: Recycle evaluation and Eco-account update failed due to internal server error
          content:
            '*/*':
              schema:
                type: string
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"
  #-----------------------------------------------------------------------------
  # 3. Endpoints for retrieving Eco-credits of evaluated product or estimation
  # of evaluation
  # USER_R_02: Get Eco-credit from evaluated recycled product
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /ecocredits/{productid}/{years}/{extramonths}/{eolstate}:
    get:
      description: USER_R_02 Get Eco-credits from evaluated recycled product
      operationId: EcoCreditsGET
      parameters:
        - in: path
          name: productid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/ProductID"
        - in: path
          name: years
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/yearsofuse"
        - in: path
          name: extramonths
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/monthsofuse"
        - in: path
          name: eolstate
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/EndOfLifeState"
      responses:
        '200':
          description: The Eco-credits result value.
          content:
            application/json:
              schema:
                $ref: "CommonOpenAPI.yaml#/components/schemas/EcoCredits"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # USER_R_04: Get Eco-credit estimation for recycled item for user incentive
  # The estimation is done on the assumptions that the product is recycled today
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /ecocredits/estimation/{productid}/{eolstate}:
    get:
      description: USER_R_04 Get Eco-credits estimation for recycled item for user incentive.
      operationId: EcoCreditsProductEstimationGET
      parameters:
        - in: path
          name: productid
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/ProductID"
        - in: path
          name: eolstate
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/EndOfLifeState"
      responses:
        '200':
          description: The Eco-credits result value for each End of Life product state.
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/EcoCreditsEstimation"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"

  # Get rough estimation from product type/category instead of specific product
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /ecocredits/estimation/type/{hskey}/{eolstate}:
    get:
      description: USER_R_04 Get Eco-credits estimation for recycled item for user incentive.
      operationId: EcoCreditsProductTypeEstimationGET
      parameters:
        - in: path
          name: hskey
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/HSkey"
        - in: path
          name: eolstate
          required: true
          schema:
            $ref: "CommonOpenAPI.yaml#/components/schemas/EndOfLifeState"
      responses:
        '200':
          description: The Eco-credits result value for each End of Life product state.
          content:
            application/json:
              schema:
                $ref:  "#/components/schemas/EcoCreditsEstimation"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"
  #-----------------------------------------------------------------------------
  # 4. Endpoints for product types
  # VALID USER SESSION/ACCESS TOKEN REQUIRED
  /product_types:
    get:
      description: Get list of product types
      operationId: ProductTypesGET
      parameters:
        - in: query
          name: locale
          required: false
          schema:
            description: ISO 639 alpha-2 language code for this locale
            type: string
            default: "en"
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: List of supported product types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "CommonOpenAPI.yaml#/components/schemas/ProductType"
        # Any response that is not HTTP/200 OK is considered an error.
        default:
          $ref: "CommonOpenAPI.yaml#/components/responses/DefaultError"
################################################################################
