---
openapi: 3.0.3
info:
  title: ELEKEY Charging Rest-Service
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.1-SNAPSHOT
paths:
  /authentication/login:
    post:
      tags:
      - Authentication Resource
      summary: Login
      description: REST-Method to return a JsonWebToken (JWT) if username and password
        are correct.
      requestBody:
        description: Login
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequestPayload"
      responses:
        "200":
          description: A JsonWebToken (JWT)
          content:
            text/plain:
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        "400":
          description: If username and / or password are blank.
        "403":
          description: If login fails. This may be the case when the username is not
            known or the password is wrong.
  /chargingoperation/start/confirm:
    post:
      tags:
      - Charging Operation Resource
      summary: Confirms the previous received charging offer.
      description: |
        If the user confirms the previously received charging offer the charging of the vehicle will start.

        Due to the fact that this is a simulator the start time of the charging operation is the start time of the first reservation slot.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmChargingConditionOfferRequest"
      responses:
        "200":
          description: If the previous received charging offer is confirmed the charging
            of the vehicle will start and a response with details is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmChargingConditionOfferResponse"
        "400":
          content:
            text/plain:
              examples:
                No charging offer present:
                  description: When the user tries to confirm an charging offer that
                    does not exist.
                  value: No charging offer present
        "401":
          description: If there is no JWT token present or user is not found.
        "403":
          description: Not Allowed
      security:
      - SecurityScheme: []
  /chargingoperation/start/request:
    post:
      tags:
      - Charging Operation Resource
      summary: Requests the start of the charging operation.
      description: |
        A user requests the start of the charging operation for a given reservation.

        As response he gets a charging offer that contains the charging conditions and other informations.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestStartChargingRequest"
      responses:
        "200":
          description: A charging offer response that contains the charing conditions
            and other informations.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestStartChargingResponse"
        "400":
          content:
            text/plain:
              schema:
                oneOf:
                - $ref: "#/components/schemas/BadRequestException"
              examples:
                No reservation present:
                  description: No reservation was found for the given reservationUuid
                  value: No reservation present
                There is already a charging operation running. Can not start another one.:
                  description: |
                    A charging operation is already running for this reservation. It is not possible to start a second one
                    unless the first one has been stopped.
                  value: There is already a charging operation running. Can not start
                    another one.
        "401":
          description: If there is no JWT token present or user is not found.
        "403":
          description: Not Allowed
      security:
      - SecurityScheme: []
  /chargingoperation/stop:
    post:
      tags:
      - Charging Operation Resource
      summary: Stops a running charging operation.
      description: Stops a charging operation. Due to the fact that this is a simulator
        the stopTime is the end time of the last reservation slot the operation is
        associated with.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StopChargingRequest"
      responses:
        "200":
          description: The charging operation has stopped successfully and a receipt
            is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StopChargingResponse"
        "400":
          content:
            text/plain:
              examples:
                No charging operation present:
                  description: When the user tries to stop a charging operation that
                    does not exist.
                  value: No charging operation present
        "401":
          description: If there is no JWT token present or user is not found.
        "403":
          description: Not Allowed
      security:
      - SecurityScheme: []
  /chargingpoint/getpaged:
    get:
      tags:
      - Charging Point Resource
      summary: Returns the charging points that can be conveyed by ELEKEY.
      description: Returns a list of charging points. Page numbers start with 0. The
        List of charging points can contain only 200
      parameters:
      - name: page
        in: query
        description: The number of the page to return
        required: true
        schema:
          format: int32
          type: integer
        example: 5
      responses:
        "200":
          description: A list of charging points.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetChargingPointsResponse"
        "400":
          content:
            text/plain:
              examples:
                The given Page Number must be 0 oder greater.:
                  description: When the passed number of the page to be returned is
                    negative.
                  value: The given Page Number must be 0 oder greater.
        "403":
          description: Not Allowed
        "401":
          description: Not Authorized
      security:
      - SecurityScheme: []
  /chargingpoint/searchforradius:
    get:
      tags:
      - Charging Point Resource
      summary: Searches charging points within a given radius.
      description: Searches charging points that are located inside of a given radius.
        The radius may be minimum 1000 and maximum 50000 meters
      parameters:
      - name: latitude
        in: query
        description: The latitude of the charging points location
        required: true
        schema:
          format: double
          type: number
        example: 48.409847
      - name: longitude
        in: query
        description: The longitude of the charging points location
        required: true
        schema:
          format: double
          type: number
        example: 9.940684
      - name: radiusInMeter
        in: query
        description: The search radius that may be minimum 1000 and maximum 50000
          meters.
        required: true
        schema:
          format: int32
          type: integer
        example: 2000
      - name: pointInTime
        in: query
        required: true
        schema:
          format: date-time
          description: A DateTime String
          type: string
          example: 2017-07-21T17:32:28+01:00
      responses:
        "200":
          description: Returns the found charging points.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ChargingPointWithStateRO"
        "400":
          content:
            text/plain:
              examples:
                Required Argument not given:
                  description: When an argument is required but was not passed in
                    the request
                  value: The given argument <name of the argument> is mandatory but
                    was not given.
                Search radius smaller than allowed:
                  description: When the passed search radius is smaller than allowed
                  value: The given argument radiusInMeter violates a constraint. The
                    search radius may not be smaller than 1000 meter.
                Search radius greater than allowed:
                  description: When the passed search radius is greater than allowed
                  value: The given argument radiusInMeter violates a constraint. The
                    search radius may not be greater than 50000 meter.
                Wrong datetime format:
                  description: "When the passed datetime string is in the wrong format.\
                    \ Pattern: yyyy-MM-dd'T'HH:mm:ssXXX"
                  value: The given dateTime String <malformed datetime string> of
                    the argument pointInTime is not in the right format (yyyy-MM-dd'T'HH:mm:ssXXX)
        "403":
          description: Not Allowed
        "401":
          description: Not Authorized
      security:
      - SecurityScheme: []
  /chargingpoint/statebyid:
    get:
      tags:
      - Charging Point Resource
      summary: Gets a charging point and its state by the chargingPointId.
      description: Returns a charging point and its state by the given chargingPointId.
        By passing a date the information is given if a reservation can be done.
      parameters:
      - name: chargingPointId
        in: query
        description: The identifier of a chargingPoint that is conveyed by ELEKEY
        required: true
        schema:
          type: string
        example: ECP#00000055
      - name: pointInTime
        in: query
        required: true
        schema:
          format: date-time
          description: A DateTime String
          type: string
          example: 2017-07-21T17:32:28+01:00
      responses:
        "200":
          description: The requested charging point an its state. If no charging point
            was found for the given id null is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargingPointWithStateRO"
        "400":
          description: If any parameter validation fails.
        "403":
          description: Not Allowed
        "401":
          description: Not Authorized
      security:
      - SecurityScheme: []
  /reservation/cancel:
    put:
      tags:
      - Reservation Resource
      summary: Cancels a reservation slot or the whole reservation
      description: |
        REST-Method to cancel a reservation slot.

        If all reservation slots have been cancelled the whole reservation
        itself is also cancelled.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelReservationRequest"
      responses:
        "200":
          description: If the reservation slot or the whole reservation was cancelled
            successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelReservationResponse"
        "401":
          description: If there is no user found
        "400":
          content:
            text/plain:
              schema:
                oneOf:
                - $ref: "#/components/schemas/BadRequestException"
              examples:
                No reservation slot found:
                  description: There was not reservation slot found for the given
                    reservationSlotUuid. This may be the case if there is no reservation
                    slot for this particular uuid or the reservation slot does not
                    belong to the user.
                  value: No reservation slot found
                Reservation slot not first or last:
                  description: The reservation slot to cancel is not the first or
                    last in the chain of reservation slots
                  value: Cancellation of a ReservationSlot ist only possible if it
                    is the first or last Slot in the chain.
        "403":
          description: Not Allowed
      security:
      - SecurityScheme: []
  /reservation/create:
    post:
      tags:
      - Reservation Resource
      summary: Creates a new reservation for a given chargingPoint and time range.
      description: |
        Method to create a new reservation for a chargingPoint and time range.

        If the minutes of the from and to datetime variables are not exact 0, 15, 30 or 45 they are adjusted to this minutes automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateReservationRequest"
      responses:
        "200":
          description: If the creation of the reservation and its reservation slots
            was successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateReservationResponse"
        "400":
          content:
            text/plain:
              schema:
                oneOf:
                - $ref: "#/components/schemas/BadRequestException"
              examples:
                No charging point found:
                  description: There was no charging point found for the given chargingPointId.
                  value: No charging point found
                A reservation already exists for the requested time range.:
                  description: "The user wants to create a reservation for a chargingPoint,\
                    \ but for the requested time range is already a reservation present.Therefore\
                    \ it is not possible to create a new reservation."
                  value: A reservation already exists for the requested time range.
        "403":
          description: Not Allowed
        "401":
          description: Not Authorized
      security:
      - SecurityScheme: []
  /reservation/keepalive:
    put:
      tags:
      - Reservation Resource
      summary: Keeps a reservation alive
      description: |
        Method to keep a reservation of a charging slot alive.

        In this simulator scenario the result is always OK, because the keep reservation alive request has no effect.
        This is because there is no scheduler which could possibly cancel a reservation automatically
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KeepReservationAliveRequest"
      responses:
        "200":
          description: If a keep alive request was successful the value OK is returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeepReservationAliveResponse"
        "403":
          description: Not Allowed
        "401":
          description: Not Authorized
      security:
      - SecurityScheme: []
components:
  schemas:
    BadRequestException:
      type: object
    CancelReservationRequest:
      type: object
      properties:
        reservationSlotUUID:
          $ref: "#/components/schemas/UUID"
    CancelReservationResponse:
      description: A Pojo that represents the response of the cancel reservation operation.
      type: object
      properties:
        result:
          type: string
          example: OK
    ChargingPointOperatingState:
      enum:
      - "ON"
      - "OFF"
      type: string
    ChargingPointRO:
      description: A pojo that represents a charging point.
      required:
      - id
      type: object
      properties:
        id:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        latitude:
          format: double
          description: The latitude of the charging points location
          type: number
          example: 48.409847
        longitude:
          format: double
          description: The longitude of the charging points location
          type: number
          example: 9.940684
        capacityKw:
          format: double
          type: number
        providerId:
          description: The id of the provider. This is the BEDW Code.
          type: string
          example: DU MMY
        providerName:
          description: The name of the provider
          type: string
          example: ABC Engery AG
        connectors:
          description: A list of connectors this charging point provides
          type: array
          items:
            $ref: "#/components/schemas/Connector"
    ChargingPointStateRO:
      type: object
      properties:
        operatingState:
          $ref: "#/components/schemas/ChargingPointOperatingState"
        currentAvailableCapacityKwh:
          format: double
          type: number
        presumedAvailableCapacityKwh:
          format: double
          type: number
        currentPriceKwh:
          format: int32
          type: integer
        presumedPriceKwh:
          format: int32
          type: integer
        meterReading:
          format: int32
          type: integer
        reservationTimeframes:
          type: array
          items:
            $ref: "#/components/schemas/ReservationTimeframeRO"
    ChargingPointWithStateRO:
      type: object
      properties:
        chargingPoint:
          $ref: "#/components/schemas/ChargingPointRO"
        chargingPointState:
          $ref: "#/components/schemas/ChargingPointStateRO"
    ConfirmChargingConditionOfferRequest:
      type: object
      properties:
        chargingOfferingUuid:
          $ref: "#/components/schemas/UUID"
        confirm:
          type: boolean
    ConfirmChargingConditionOfferResponse:
      description: |
        A pojo that represents the response of the condition offer confirmation.
      required:
      - chargingPointId
      type: object
      properties:
        chargingOperationUuid:
          $ref: "#/components/schemas/UUID"
        chargingOfferingUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointId:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        meterIdentifier:
          type: string
        meterReading:
          format: int32
          type: integer
        priceKwh:
          format: int32
          type: integer
        startTime:
          type: string
        providerId:
          description: The id of the provider. This is the BEDW Code.
          type: string
          example: DU MMY
        providerName:
          description: The name of the provider
          type: string
          example: ABC Engery AG
        customerName:
          description: The name of the logistican
          type: string
          example: Speedy Gonzales Transportations
        customerUuid:
          $ref: "#/components/schemas/UUID"
        username:
          description: The name of the user who reqeusts the start of the charging
            operation. May be the same as the logisticans name.
          type: string
          example: Hans Dampf
        userUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointLatitude:
          format: double
          description: The latitude of the charging points location
          type: number
          example: 48.409847
        chargingPointLongitude:
          format: double
          description: The longitude of the charging points location
          type: number
          example: 9.940684
    Connector:
      description: Pojo that represents a connector / plug.
      required:
      - value
      - getDescription
      type: object
      properties:
        value:
          description: The identifier of the connector
          enum:
          - AC_CEE_5_POLIG
          - AC_KUPPLUNG_TYP2
          - AC_CEE_3_POLIG
          - AC_SCHUKO
          - DC_CHADEMO
          - ADAPTER_TYP1_AUTO_AUF_TYP2
          - DC_KUPPLUNG_COMBO
          - AC_STECKDOSE_TYP2
          - AC_CEE
          - AC_CEE_3_POLIG_5_POLIG
          - CEE_STECKER
          - COMPLEO_DUO_BM
          - TYP_3
          - DC_KUPPLUNG_TESLA_TYP2
          - TESLA
          - TYP_2_TESLA
          type: string
          example: AC_STECKDOSE_TYP2
        getDescription:
          description: A description that provides more details than the value itself.
          type: string
          example: AC Steckdose Typ 2
    ConnectorType:
      $ref: "#/components/schemas/ConnectorType"
    CreateReservationRequest:
      description: A pojo that represents the CreateReservationRequest body.
      required:
      - chargingPointId
      - from
      - to
      type: object
      properties:
        chargingPointId:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        from:
          description: "The datetime the reservation shall start. Pattern: yyyy-MM-dd'T'HH:mm:ssXXX"
          type: string
          example: 2024-03-03T20:00:00+01:00
        to:
          description: "The datetime the reservation shall end. Pattern: yyyy-MM-dd'T'HH:mm:ssXXX"
          type: string
          example: 2024-03-03T20:45:00+01:00
    CreateReservationResponse:
      description: A pojo that represents the createReservation response.
      required:
      - chargingPointId
      - reservationUuid
      - reservationSlots
      type: object
      properties:
        chargingPointId:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        reservationUuid:
          description: The UUID of the created reservation.
          type: string
          allOf:
          - $ref: "#/components/schemas/UUID"
        reservationSlots:
          description: A list of reservation slots the created reservations is detailed
            by.
          type: array
          items:
            $ref: "#/components/schemas/ReservationSlotRO"
    ErrorDetail:
      description: "A pojo that holds informations about an error, when the response\
        \ result was not OK"
      type: object
      properties:
        errorReferenceId:
          description: A UUID that references the error on the server.
          type: string
          allOf:
          - $ref: "#/components/schemas/UUID"
        errorMessage:
          description: Error message text that contains details about the error.
          type: string
          example: A communication problem with the charging point has occured.
    GetChargingPointsResponse:
      description: A pojo that represents the response body.
      type: object
      properties:
        chargingPoints:
          description: A list of charging points.
          type: array
          items:
            $ref: "#/components/schemas/ChargingPointRO"
        maxPages:
          format: int32
          description: The number of page which can be queried.
          type: integer
          example: 511
        currentPage:
          format: int32
          description: The number of the page the data of this response is from.
          type: integer
          example: 5
    KeepReservationAliveRequest:
      description: Request payload object to keep a reservation alive.
      required:
      - slotReservationId
      type: object
      properties:
        slotReservationId:
          description: The UUID of a reservation slot
          type: string
          allOf:
          - $ref: "#/components/schemas/UUID"
    KeepReservationAliveResponse:
      description: A pojo that represents the KeepReservationAlive response body with
        an optional errorDetail object.
      required:
      - result
      type: object
      properties:
        result:
          description: A result string that contains informations about the reservation
            keep alive operation
          type: string
          example: OK
        errorDetail:
          description: "If the result is not OK, the errorDetail response object will\
            \ contain details"
          type: object
          allOf:
          - $ref: "#/components/schemas/ErrorDetail"
          nullable: true
    LoginRequestPayload:
      description: A Pojo that represents the login request body
      required:
      - username
      - password
      type: object
      properties:
        username:
          pattern: \S
          type: string
          example: max.mustermann
        password:
          pattern: \S
          type: string
          example: AwesomeSecretPassword123
    RequestStartChargingRequest:
      required:
      - reservationUuid
      type: object
      properties:
        reservationUuid:
          $ref: "#/components/schemas/UUID"
    RequestStartChargingResponse:
      description: |
        A pojo that represents the response of the request to start charging.
      required:
      - chargingPointId
      type: object
      properties:
        chargingOfferingUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointId:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        meterIdentifier:
          type: string
        meterReading:
          format: int32
          type: integer
        priceKwh:
          format: int32
          type: integer
        providerId:
          description: The id of the provider. This is the BEDW Code.
          type: string
          example: DU MMY
        providerName:
          description: The name of the provider
          type: string
          example: ABC Engery AG
        customerName:
          description: The name of the logistican
          type: string
          example: Speedy Gonzales Transportations
        customerUuid:
          $ref: "#/components/schemas/UUID"
        username:
          description: The name of the user who reqeusts the start of the charging
            operation. May be the same as the logisticans name.
          type: string
          example: Hans Dampf
        userUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointLatitude:
          format: double
          description: The latitude of the charging points location
          type: number
          example: 48.409847
        chargingPointLongitude:
          format: double
          description: The longitude of the charging points location
          type: number
          example: 9.940684
    ReservationAvailability:
      enum:
      - BLOCKED
      - AVAILABLE
      type: string
    ReservationSlotRO:
      description: "A pojo that represents a reservation slot. A Slot has a dimension\
        \ of 15 minutes. Possible time ranges are 0-15, 15-30, 30-45 and 45-60."
      required:
      - slotReservationUuid
      - from
      - to
      type: object
      properties:
        slotReservationUuid:
          description: The UUID the identifies a reservation slot.
          type: string
          allOf:
          - $ref: "#/components/schemas/UUID"
        from:
          description: "The datetime the reservation slot starts. Pattern: yyyy-MM-dd'T'HH:mm:ssXXX"
          type: string
          example: 2024-03-03T19:45:00+01:00
        to:
          description: "The datetime the reservation slot ends. Pattern: yyyy-MM-dd'T'HH:mm:ssXXX"
          type: string
          example: 2024-03-03T20:00:00+01:00
    ReservationTimeframeRO:
      type: object
      properties:
        from:
          format: date-time
          description: An ISO 8601 DateTime String
          type: string
          example: 2017-07-21T17:32:00+01:00
        to:
          format: date-time
          description: An ISO 8601 DateTime String
          type: string
          example: 2017-07-21T17:32:00+01:00
        reservationAvailability:
          $ref: "#/components/schemas/ReservationAvailability"
    StopChargingRequest:
      description: Pojo that represents the stop charging response body
      type: object
      properties:
        chargingOperationUuid:
          description: "The UUID of the charging operation, that was stopped."
          type: string
          allOf:
          - $ref: "#/components/schemas/UUID"
    StopChargingResponse:
      required:
      - chargingPointId
      type: object
      properties:
        chargingOperationUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointId:
          description: The identifier of a chargingPoint that is conveyed by ELEKEY
          type: string
          example: ECP#00000055
        meterIdentifier:
          type: string
        meterReadingStart:
          format: int32
          type: integer
        meterReadingStop:
          format: int32
          type: integer
        chargedWattHours:
          format: int32
          type: integer
        priceKwh:
          format: int32
          type: integer
        startTime:
          type: string
        stopTime:
          type: string
        chargingDurationSecs:
          format: int32
          type: integer
        providerId:
          description: The id of the provider. This is the BEDW Code.
          type: string
          example: DU MMY
        providerName:
          description: The name of the provider
          type: string
          example: ABC Engery AG
        customerName:
          description: The name of the logistican
          type: string
          example: Speedy Gonzales Transportations
        customerUuid:
          $ref: "#/components/schemas/UUID"
        username:
          description: The name of the user who reqeusts the start of the charging
            operation. May be the same as the logisticans name.
          type: string
          example: Hans Dampf
        userUuid:
          $ref: "#/components/schemas/UUID"
        chargingPointLatitude:
          format: double
          description: The latitude of the charging points location
          type: number
          example: 48.409847
        chargingPointLongitude:
          format: double
          description: The longitude of the charging points location
          type: number
          example: 9.940684
    UUID:
      format: uuid
      pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
      type: string
  securitySchemes:
    SecurityScheme:
      type: http
      description: Authentication
      scheme: bearer
      bearerFormat: JWT
