openapi: 3.2.0
info:
  title: V2X App Deposit API
  description: API for Vehicle-to-Everything (V2X) Multi-Access Edge Computing (MEC) services. This App API provides endpoints for ETX registration, V2X Message Deposit, and authentication services.
  version: 1.0.0
servers:
- url: http://localhost:8080
  description: Generated server url
security:
- BearerAuth: []
tags:
- name: Deposit
  description: V2X Message Deposit endpoints for deployment to the ETX MQTT Broker
paths:
  /prd/v2/deposit/geofence:
    post:
      tags:
      - Deposit
      summary: Deposit V2X Message
      description: Deposits V2X message data to the database. This endpoint is used to deploy V2X messages (TIM, MAP, etc.) with geospatial information. The configuration must include geofence overrides to define the deployment area. Vendor ID is automatically determined from the user's JWT token based on their role.
      operationId: deposit
      requestBody:
        description: Configuration data to deposit
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
        required: true
      responses:
        '200':
          description: V2X message deployed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceDeploymentResponse'
        '400':
          description: Bad request - invalid configuration data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json: {}
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json: {}
        '409':
          description: Conflict - no available geohash or conflicting state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large - exceeds maximum allowed geohashes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity - invalid ASN.1 data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
    delete:
      tags:
      - Deposit
      summary: Delete geofence by identifier
      description: Deletes geofence deployments associated with a specific identifier. This endpoint allows for manual removal of geofence deployments by their identifier. The system will deactivate the geofence deployment by setting is_active to false. This follows REST best practices by using query parameters for resource identification.
      operationId: deleteGeofence_1
      parameters:
      - name: identifier
        in: query
        description: Geofence identifier to delete
        required: true
        schema:
          type: string
        example: GEOFENCE_12345
      responses:
        '204':
          description: Geofence deleted successfully
          content:
            '*/*':
              schema:
                type: object
        '400':
          description: Bad request - invalid identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json: {}
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json: {}
        '404':
          description: Not found - no geofence found with the specified identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
components:
  schemas:
    MultiPolygon:
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: array
                  items:
                    type: number
                    format: double
    Polygon:
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: number
                  format: double
    LineString:
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: number
                format: double
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        description:
          type: string
    DepositRequest:
      type: object
      description: Request model for V2X message deposit
      properties:
        asn1_hex:
          type: string
          description: UPER-encoded MessageFrame containing a MAP or TIM V2X Message in hexadecimal format
        override_geofence:
          $ref: '#/components/schemas/GeofenceFeatureCollection'
          description: Override Geofence for ETX deployment. If not set, the geofence will be extracted from the provided message
      required:
      - asn1_hex
    Geometry:
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
      required:
      - type
    MultiLineString:
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: number
                  format: double
    GeofenceFeature:
      type: object
      description: GeoJSON Feature representing a single geometric element within a geofence
      properties:
        type:
          type: string
          description: GeoJSON type, must be 'Feature'
          example: Feature
        geometry:
          description: GeoJSON geometry object defining the spatial extent
          oneOf:
          - $ref: '#/components/schemas/LineString'
          - $ref: '#/components/schemas/MultiLineString'
          - $ref: '#/components/schemas/MultiPolygon'
          - $ref: '#/components/schemas/Polygon'
        properties:
          additionalProperties: false
          description: 'Properties object is required and must be an empty object. No content is allowed in the properties object. Must be an empty JSON object: {}. Any properties within this object will cause validation to fail. This field enforces that the properties object contains no key-value pairs.'
          example: {}
      required:
      - properties
    GeofenceDeploymentResponse:
      type: object
      description: Response model for Geofence deployment
      properties:
        id:
          type: integer
          format: int64
          description: Database ID of the Geofence deployment
        geofence_id:
          type: string
          description: Unique identifier for the Geofence deployment
        geojson:
          $ref: '#/components/schemas/GeofenceFeatureCollection'
          description: GeoJSON FeatureCollection representation of the deployment area
        hex_payload:
          type: string
          description: ASN.1 encoded message in hexadecimal format
        deployed_by:
          type: string
          description: Username of the person who deployed the Geofence
        is_active:
          type: boolean
          description: Whether the Geofence deployment is currently active
        created_at:
          type: string
          format: date-time
          description: Timestamp when the Geofence was deployed
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the Geofence was last updated
        expires_at:
          type: string
          format: date-time
          description: Optional expiration timestamp for the Geofence deployment
        geohashes:
          type: array
          description: List of geohashes covering the deployment area
          items:
            type: string
    GeofenceFeatureCollection:
      type: object
      description: GeoJSON FeatureCollection representing a geofence area
      properties:
        type:
          type: string
          description: GeoJSON type, must be 'FeatureCollection'
          example: FeatureCollection
        features:
          type: array
          description: Array of GeoJSON features defining the geofence geometry
          items:
            $ref: '#/components/schemas/GeofenceFeature'
  securitySchemes:
    BearerAuth:
      type: http
      description: Keycloak JWT Bearer Token. Required for all endpoints except decode endpoints. Obtain a token from the /auth/token endpoint using your credentials.
      scheme: bearer
      bearerFormat: JWT