add /subscription-endpoint for location-area

code/API_definitions/location.yaml

@@ -13,11 +13,12 @@ externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
 security:
-  - oAuth2ClientCredentials: []
-#  - BasicAuth: []
-#  - apiKey: []
+  - oAuth2ClientCredentials: [ ]
+  #  - BasicAuth: []
+  #  - apiKey: []
   - three_legged:
-    - device-location-read
+      - device-location-tracking
+      - device-location-read
 servers:
   - url: '{apiRoot}/{basePath}'
     variables:
@@ -81,22 +82,69 @@ paths:
           $ref: '#/components/responses/Generic500'
         '503':
           $ref: '#/components/responses/Generic503'
+  /subscriptions:
+    post:
+      tags:
+        - Location Subscription
+      summary: 'Create a location subscription for a device'
+      operationId: createSubscription
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateSubscription'
+        required: true
+      responses:
+        '201':
+          description: Created (Successful creation of subscription)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SubscriptionInfo'
+        '400':
+          $ref: '#/components/responses/Generic400'
+        '401':
+          $ref: '#/components/responses/Generic401'
+        '403':
+          $ref: '#/components/responses/Generic403'
+        '409':
+          $ref: '#/components/responses/Generic409'
+        '500':
+          $ref: '#/components/responses/Generic500'
+        '503':
+          $ref: '#/components/responses/Generic503'
+  /notifications:
+    post:
+      tags:
+        - Notification Callback
+      summary: "Subscription notification callback"
+      operationId: postNotification
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Notification"
+      responses:
+        '204':
+          description: No Content
+
 components:
   securitySchemes:
     oAuth2ClientCredentials:
       type: oauth2
       flows:
         clientCredentials:
           tokenUrl: '{tokenUrl}'
-          scopes: {}
-#    BasicAuth:
-#      type: http
-#      scheme: basic
-#    apiKey:
-#      type: apiKey
-#      description: API key to authorize requests
-#      name: apikey
-#      in: query
+          scopes: { }
+    #    BasicAuth:
+    #      type: http
+    #      scheme: basic
+    #    apiKey:
+    #      type: apiKey
+    #      description: API key to authorize requests
+    #      name: apikey
+    #      in: query
     three_legged:
       type: oauth2
       flows:
@@ -199,6 +247,11 @@ components:
         ipv6Addr:
           $ref: '#/components/schemas/Ipv6Addr'
       minProperties: 1
+    UeIdList:
+      description: List of User equipment identifiers
+      type: array
+      items:
+        $ref: '#/components/schemas/UeId'
     ExternalId:
       type: string
       example: '[email protected]'
@@ -220,9 +273,7 @@ components:
     Ipv6Addr:
       type: string
       format: ipv6
-      allOf:
-        - pattern: '^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$'
-        - pattern: '^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$'
+      pattern: '(^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$)|(^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$)'
       example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
       description: |
         IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
@@ -272,6 +323,108 @@ components:
         message:
           type: string
           description: Detailed error description
+    LocationEventType:
+      description: |
+        AREA_ENTERED - Location event triggered when the UE entered the given area
+        AREA_LEFT - Location event triggered when the UE left the given area
+      type: string
+      enum:
+        - AREA_ENTERED
+        - AREA_LEFT
+    LocationEventTypeList:
+      description: List of Location Event Type
+      type: array
+      items:
+        $ref: '#/components/schemas/LocationEventType'
+      example: [ AREA_ENTERED, AREA_LEFT ]
+    CreateSubscription:
+      description: The request for creating a Location Subscription
+      type: object
+      properties:
+        ueId:
+          $ref: '#/components/schemas/UeId'
+        eventTypes:
+          $ref: '#/components/schemas/LocationEventTypeList'
+        area:
+          $ref: '#/components/schemas/Area'
+        notificationUrl:
+          type: string
+          example: "https://application-server.com"
+          description: Allows asynchronous delivery of aread-location related events
+        notificationAuthToken:
+          type: string
+          example: "c8974e592c2fa383d4a3960714"
+          description: Authentication token for callback API
+        subscriptionExpireTime:
+          type: string
+          format: date-time
+          example: 2023-01-17T13:18:23.682Z
+          description: The time when the location-tracking has to be terminated (e.g. in 14 days from now on). Provided in date-time format.
+        startedAt:
+          type: string
+          format: date-time
+          example: 2023-01-17T13:18:23.682Z
+          description: The time when the location-tracking has to be started (e.g. in 7 days from now on). Provided in date-time format.
+      required:
+        - ueIds
+        - eventTypes
+        - notificationUrl
+        - notificationAuthToken
+        - subscriptionExpireTime
+    SubscriptionInfo:
+      description: Represents a area-location subscription.
+      type: object
+      allOf:
+        - $ref: '#/components/schemas/CreateSubscription'
+        - type: object
+          properties:
+            subscriptionId:
+              $ref: '#/components/schemas/SubscriptionId'
+            startedAt:
+              type: string
+              format: date-time
+            expiresAt:
+              type: string
+              format: date-time
+          required:
+            - subscriptionId
+            - startedAt
+            - expiresAt
+    Area:
+      description: The definition of an area described by a geographical point and accuracy.
+      type: object
+      properties:
+        latitude:
+          $ref: '#/components/schemas/Latitude'
+        longitude:
+          $ref: '#/components/schemas/Longitude'
+        accuracy:
+          $ref: '#/components/schemas/Accuracy'
+    SubscriptionId:
+      type: string
+      description: The subscription identifier.
+    EventTime:
+      format: date-time
+      type: string
+      description: The time when the event was notified.
+    Notification:
+      description: The notification callback.
+      type: object
+      required:
+        - subscriptionId
+        - event
+        - eventTime
+        - ueId
+      properties:
+        subscriptionId:
+          $ref: '#/components/schemas/SubscriptionId'
+        ueId:
+          $ref: '#/components/schemas/UeId'
+        eventType:
+          $ref: "#/components/schemas/LocationEventType"
+        eventTime:
+          $ref: '#/components/schemas/EventTime'
+
   responses:
     Generic400:
       description: Invalid input
@@ -313,6 +466,15 @@ components:
             status: 404
             code: NOT_FOUND
             message: 'The specified resource is not found'
+    Generic409:
+      description: Conflict
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            code: CONFLICT
+            message: "The specified resource is in a conflict"
     Generic500:
       description: Internal server error
       content: