openapi: "3.0.0"


################################################################################
# General Information
# SYSTEM_32: Web Applications/Services
info:
  description: The ICT Platform Web Services common models and paths
  version: 1.0.2
  title: ICT Platform Web Services Common
  contact:
    name: Miltiadis Koutsokeras
    email: miltos.koutsokeras@iccs.gr
    url: https://www.iccs.gr/

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


################################################################################
# Components
components:
  # All secured endpoints use the OpenID Connect Discovery for
  # authentication/authorization. The security implementation is provided from
  # an external service based on Keycloak.
  securitySchemes:
    OpenIDConnect:
      description: OpenID Connect Discovery security for REST endpoints
      type: openIdConnect
      openIdConnectUrl: https://circ4life.iccs.gr/auth/realms/CIRC4LIFE/.well-known/uma2-configuration

  # General type of responses used by multiple endpoints
  responses:
    DefaultSuccess:
      description: Default success response HTTP 2xx
      content:
        '*/*':
          schema:
            type: string

    DefaultError:
      description: Default error response HTTP 4xx, 5xx
      content:
        '*/*':
          schema:
            type: string

  # Data models are common structures for describing information and
  # encapsulating various properties
  schemas:
    Address:
      description: Postal address
      type: object
      required:
        - country
        - postalcode
        - street
        - city
      properties:
        country:
          # 2 characters length only
          description: Country 2 letter ISO 639 alpha-2 code
          type: string
          example: GR
        postalcode:
          # Cannot be an empty string
          description: Postal code of address area
          type: string
          example: 100157
        street:
          # Cannot be an empty string
          description: Street address (street name, number, city, area)
          type: string
          example: 9, Iroon Politechniou Str. Zografou
        city:
          # Cannot be an empty string
          description: The locality in which the street address is located.
          type: string
          example: Athens
        region:
          # Cannot be an empty string
          description: The region in which the city belongs.
          type: string
          example: Attica

    # All services can accept dates as input parameters in the ISO format:
    # yyyy-MM-dd
    # Digits: y = year, M = month, d = day
    # Examples:
    # 2011-12-03
    # Any other format is probably not parsable.
    # Details for Java class: https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_DATE
    Date:
      description: Date representation yyyy-MM-dd
      type: string

    Locale:
      description: ISO 639 alpha-2 language code for this locale
      type: string
      default: "en"
      minLength: 2
      maxLength: 2

    GTIN:
      description: Product GTIN code
      type: integer
      format: int64

    UNUkey:
      description: Electronic product UNU-KEY code as described in https://unu.edu/projects/e-waste-quantification.html#outputs.
      type: integer
      format: int32
      minimum: 1
      example: 303 # Laptops, tablets

    HSkey:
      description: Product Harmonized System 6 digit code as described in http://www.wcoomd.org/en/topics/nomenclature/overview/what-is-the-harmonized-system.aspx.
      type: integer
      format: int32
      minimum: 1
      maximum: 999999
      # Portable digital data product (corresponds to UNU key 303)
      example: 847130

    EndOfLifeState:
      description: Product End of Life state, should be one of 'working', 'repairable', 'broken'. Not present when refered product is bio-waste.
      type: string
      # BUG: OpenApi generator creates a Java enum but it does not instantiate
      # it properly from the URI path
      #enum:
      #  - working
      #  - repairable
      #  - broken

    yearsofuse:
      description: Years of product use thus far.
      type: integer
      format: int32
      minimum: 0
      maximum: 100

    monthsofuse:
      description: Additional months of use added to years of use.
      type: integer
      format: int32
      minimum: 0
      maximum: 11

    EcoCredits:
      description: Value of Eco-credits
      type: number
      format: double
      minimum: 0.0

    EcoPoints:
      description: Value of Eco-points
      type: number
      format: double
      minimum: 0.0

    EcoDebits:
      description: Value of Eco-debits
      type: number
      format: double
      minimum: 0.0

    # Product ID string. Format used is GTIN14.SerialNumber
    # It is possible to only provide the GTIN14 in case the service call
    # requires only the Product model and not an individual item.
    ProductID:
      description: Product ID as in the unique identification properties of Product Master Data record.
      type: string
      minLength: 14
      # GTIN14 only
      example: 04047111123453
      # GTIN14 + Serial Number (SGTIN compatible)
      # example: 04047111123453.012345678901

    # Product scanned barcode formatted as GS1-128 application standard.
    # Format: (01)GTIN14(21)SerialNumber
    # This should encode the same data as ProductID: GTIN + Serial Number.
    # The supported Application Identifiers (AI) are 01 (GTIN) and 21 (Serial
    # Number).
    Barcode:
      description: GS1-128 barcode with AI of 01 (GTIN) and/or 21 (Serial Number)
      type: string
      # (01) = 4, GTIN14 = 14
      minLength: 18
      # (01) = 4, GTIN14 = 14, (21) = 4, Serial Number = up to 20
      maxLength: 42
      # Check http://www.kentraub.net/tools/tagxlate/EPCEncoderDecoder.html for
      # examples.
      # Example: GTIN14 + Serial Number
      example: "(01)80614141123458(21)6789"

    # Instead of arbitrary categories of products, this data model is used to
    # describe the product type as a Harmonized System 6 digit code, with an
    # optional description and UNU key if the product falls into one of the
    # electronics types.
    ProductType:
      description: Product type encapsulation containing HS and UNU keys plus text description
      type: object
      required:
        - hskey
      properties:
        hskey:
          $ref: "#/components/schemas/HSkey"
        unukey:
          $ref: "#/components/schemas/UNUkey"
        text:
          type: string

    # This is not the full JSON-LD Product Master Data record. It is the minimum
    # set of properties that uniquely identifies a single product that is
    # purchased or recycled.
    Product:
      description: Product that can be bought.
      type: object
      required:
        - gtin
        - serialnum
        - name
        - purchasedate
      properties:
        gtin:
          $ref: "#/components/schemas/GTIN"
        serialnum:
          description: The serial number or any alphanumeric identifier of the particular product item.
          type: string
        name:
          description: The product's name
          type: string
        purchasedate:
          $ref: "#/components/schemas/Date"
        manufacturer:
          description: The product's manufacturer.
          type: string
        model:
          description: The product's model.
          type: string
        type:
          $ref: "#/components/schemas/ProductType"
        price:
          description: The product price and currency, e.g. 15 Euros. Applies to individual product items only.
          type: string
        recycledate:
          $ref: "#/components/schemas/Date"
        ecocredits:
          description: Eco-credits of this item. Applies to individual product items only.
          type: number
          format: double

    AnonymousConsumerID:
      description: A user ID that uniquely identifies an EcoAccount but has no private user data exposed.
      type: string

    RecycleBinUserID:
      description: Intelligent Bin User code as an 11 digit integer.
      type: integer
      format: int64
      minimum: 0
      maximum: 99999999999
      # ZIP code is first 5 digits (e.g. 16004), 6 last digits are sequential (e.g. 000001)
      example: 16004000001

    Organization:
      description: A user's affiliated organization, e.g. Company, University, Club, Team, etc.
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
        url:
          # Valid HTTP, HTTPs URL
          type: string

    # This random string is generated by the authorization service on succesful
    # client authentication (login). The client application should save this and
    # use it along the rest of the input parameters in order to gain access on
    # protected resources. A request to any protected resource should fail if
    # the client's access token is not valid or has expired. This is the basic
    # scheme of OAuth2 protocol. The client application should keep the access
    # token confidential as much as possible, although this is not always
    # possible. That's one of the reasons why access tokens usually have a short
    # lifetime and can only be refreshed by authorized clients. The access token
    # also encodes the scope of access: not all resources are accessible from
    # all clients/users with a valid token.
    # CAUTION: HTTPs (TLS/SSL secured channel) IS REQUIRED for this scheme of
    # authorization to work securely. Failing to exchange data between client
    # and server in an encrypted channel, undermines the whole purpose of
    # authentication/authorization.
    AccessToken:
      title: Access Control Manager Token.
      description: Access Random string generated by authorization server, used to access resources.
      type: string

    RefreshToken:
      title: Access Control Manager Refresh Token.
      description: Refresh Random string generated by authorization server, used to access resources.
      type: string
################################################################################


################################################################################
# Security
security:
  - OpenIDConnect:
    - openid
################################################################################


################################################################################
# Resource path URI endpoints
paths:
  /:
    get:
      responses:
        '200':
          $ref: "#/components/responses/DefaultSuccess"
        default:
          $ref: "#/components/responses/DefaultError"
################################################################################
